playstv-retriever

Vite + React 19 + TypeScript frontend, TanStack Router, Tailwind v4 + shadcn/ui, Convex backend.

Getting started

npm install
npm run dev        # runs Vite and `convex dev` together

Other scripts: npm run build, npm run typecheck, npm run lint.

Deploying (Vercel + Convex)

vercel.json configures the build: Vercel runs npx convex deploy, which pushes the Convex functions to the production deployment and then runs npm run build with VITE_CONVEX_URL pointing at it. All routes rewrite to index.html so client-side routes like /u/<name> work on reload.

One-time setup:

1. Create a Convex cloud project: npx convex login, then npx convex dev and choose to create a new project (this replaces the local anonymous deployment in .env.local).
2. In the Convex dashboard, open the project's Production deployment → Settings → Generate Production Deploy Key.
3. Import the GitHub repo in Vercel. Under Settings → Environment Variables, add CONVEX_DEPLOY_KEY with that key (Production environment).
4. Deploy. Every push to main then deploys both the backend and the frontend.

For Vercel preview deployments, add a Convex Preview deploy key as CONVEX_DEPLOY_KEY for the Preview environment; each preview gets its own Convex backend.

Architecture

Feature-based frontend, layered Convex backend.

convex/                     Backend (runs on Convex)
  schema.ts                 Tables + shared field validators
  model/<domain>.ts         Business logic: plain functions taking ctx
  <domain>.ts               Public API: thin query/mutation/action wrappers
  _generated/               Generated by `convex dev` (do not edit)

src/                        Frontend
  main.tsx                  Entry point
  app/                      App composition: providers, router instance
  routes/                   TanStack Router file-based routes (thin: compose features)
  routeTree.gen.ts          Generated by the router Vite plugin (do not edit, commit it)
  features/<feature>/       One folder per feature
    components/             UI for this feature
    hooks/                  Convex hooks (useQuery/useMutation) for this feature
    index.ts                Public surface: other code imports only from here
  components/ui/            shadcn/ui primitives (managed by the shadcn CLI)
  components/layout/        App-wide layout (shell, header, ...)
  lib/                      Framework-agnostic helpers (utils, env)

Rules

• Features don't reach into each other. Import from @/features/<name>, never from its internals. Code shared by several features goes in components/, lib/ or hooks/.
• Components never call api.* directly. Convex access lives in the feature's hooks/, so data shape changes stay in one place.
• Convex public functions stay thin. Validate args, then call into convex/model/. Reuse validators from schema.ts instead of redefining them.
• External HTTP (e.g. fetching archived Plays.tv pages) goes in Convex actions, which then write results through internal mutations.
• Routes are thin. A file in src/routes/ defines the URL, params/search validation and loaders, and renders feature components. Logic stays in features/.
• Don't hand-edit components/ui/. Add with npx shadcn@latest add <name>, and wrap a primitive in a feature component when you need to customise it.

Imports

• @/… → src/…
• @convex/… → convex/… (e.g. import { api } from '@convex/_generated/api')