|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## What is Starpod? |
| 6 | + |
| 7 | +Starpod is an open-source Astro-based podcast website generator. It creates a full podcast site from an RSS feed and a `starpod.config.ts` configuration file. The reference deployment is [whiskey.fm](https://whiskey.fm) (Whiskey Web and Whatnot podcast). |
| 8 | + |
| 9 | +## Commands |
| 10 | + |
| 11 | +- **Dev server:** `pnpm dev` (runs on localhost:4321) |
| 12 | +- **Build:** `pnpm build` (runs `astro check` then `astro build --remote`) |
| 13 | +- **Lint:** `pnpm lint` (ESLint with caching) |
| 14 | +- **Lint fix:** `pnpm lint:fix` |
| 15 | +- **All tests:** `pnpm test` (runs unit + e2e concurrently) |
| 16 | +- **Unit tests only:** `pnpm test:unit` (Vitest) |
| 17 | +- **Single unit test:** `pnpm exec vitest run tests/unit/Player.test.tsx` |
| 18 | +- **E2E tests only:** `pnpm test:e2e` (Playwright, auto-starts dev server) |
| 19 | +- **Seed remote DB:** `pnpm db:seed` |
| 20 | + |
| 21 | +## Architecture |
| 22 | + |
| 23 | +### Framework Stack |
| 24 | + |
| 25 | +- **Astro 5** with static output, deployed to Vercel |
| 26 | +- **Preact** for interactive components (player, search, contact form) |
| 27 | +- **Tailwind CSS v4** via Vite plugin |
| 28 | +- **Astro DB** (Turso/libSQL) for episode guests and sponsors |
| 29 | +- **Valibot** for config validation |
| 30 | + |
| 31 | +### Key Configuration |
| 32 | + |
| 33 | +- `starpod.config.ts` — podcast metadata (hosts, platforms, RSS feed URL, description). Uses `defineStarpodConfig()` from `src/utils/config.ts` for type safety and validation. |
| 34 | +- `astro.config.mjs` — Astro config with Vercel adapter, Preact, sitemap, and DB integrations. |
| 35 | + |
| 36 | +### Data Flow |
| 37 | + |
| 38 | +Episodes are fetched from the RSS feed at build time via `src/lib/rss.ts`. Guest/sponsor data lives in `db/data/` as TypeScript files and is seeded to Turso via `db/seed.ts`. The DB schema is in `db/config.ts` with tables: Episode, Person, HostOrGuest, Sponsor, SponsorForEpisode. |
| 39 | + |
| 40 | +### Source Structure |
| 41 | + |
| 42 | +- `src/pages/` — Astro pages and API routes. Dynamic episode pages use `[episode].astro`. LLM-friendly `.html.md.ts` endpoints generate markdown versions. |
| 43 | +- `src/components/` — Mix of `.astro` (static) and `.tsx` (Preact interactive) components. The audio player (`src/components/player/`) and search dialog are Preact. |
| 44 | +- `src/components/state.ts` — Preact signals for shared player state. |
| 45 | +- `src/lib/` — Core utilities: RSS fetching, image optimization, LLM content generation. |
| 46 | +- `src/content/transcripts/` — Markdown transcript files named by episode number. |
| 47 | +- `src/layouts/Layout.astro` — Single shared layout. |
| 48 | + |
| 49 | +### Testing |
| 50 | + |
| 51 | +- **Unit tests** (`tests/unit/`): Vitest + jsdom + @testing-library/preact. Setup file at `tests/unit/test-setup.ts`. |
| 52 | +- **E2E tests** (`tests/e2e/`): Playwright testing against chromium, firefox, and webkit. |
| 53 | + |
| 54 | +### TypeScript |
| 55 | + |
| 56 | +Strict mode with `baseUrl: "."` allowing bare `src/...` imports. JSX is configured for Preact (`jsxImportSource: "preact"`). |
| 57 | + |
| 58 | +## Environment Variables |
| 59 | + |
| 60 | +- `DISCORD_WEBHOOK` — Used by the contact form API route (`src/pages/api/contact.ts`) to post to Discord. |
| 61 | +- Astro DB connection requires `ASTRO_STUDIO_APP_TOKEN` for remote operations (build, seed). |
0 commit comments