CineWorm

CineWorm is a production-sensible MVP for tracking movies and TV series. It uses Next.js 16, React 19, Tailwind CSS, shadcn-style UI primitives, Supabase Auth/Postgres, TMDB metadata, and an OpenNext Cloudflare deployment target.

Stack

• Next.js 16 App Router
• React 19
• TypeScript
• pnpm
• Tailwind CSS v4
• shadcn-style component setup with Radix primitives
• Supabase Auth + Postgres
• Zod validation
• TMDB metadata API
• Cloudflare Workers via @opennextjs/cloudflare

Features

• Email/password auth with Supabase
• TMDB-backed search and detail pages for movies and TV series
• Personal library with only two states: watchlist and watched
• Fast watchlist / watched actions for movies and series
• Series episode progress with per-episode persistence
• Private note per title
• Dashboard with watchlist and simple stats
• Library filtering by type, status, genre, year, and text search
• Library sorting and grid/list view
• Poster-heavy details page with inline management controls

Local setup

1. Install dependencies:

pnpm install

2. Copy .env.example to .env.local and fill in:

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
TMDB_API_READ_TOKEN=
NEXT_PUBLIC_APP_URL=http://localhost:3000

3. Create a Supabase project.

4. Run the SQL migration from supabase/migrations/001_init.sql.

5. supabase/seed.sql is intentionally empty by default because library data is user-owned and keyed by TMDB IDs.

6. Start the app:

pnpm dev

Supabase setup

• Enable Email auth in Supabase Authentication.
• If you require email confirmation, keep the callback URL pointed at /auth/callback.
• Add your local origin and Cloudflare production URL to Supabase redirect URLs.
• The schema relies on RLS. No service role key is required for the MVP.

TMDB setup

• Create a TMDB developer account.
• Generate a read access token.
• Set TMDB_API_READ_TOKEN in .env.local and Cloudflare secrets.

Optional TVMaze note

This MVP does not need TVMaze because TMDB season endpoints already cover the episode-tracking flow. If you later hit gaps for certain long-running TV metadata cases, TVMaze can be added behind the existing TMDB service layer.

Useful commands

pnpm dev
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm build:worker
pnpm preview
pnpm deploy

Cloudflare deployment

1. Log in to Wrangler:

pnpm wrangler login

2. Set production secrets:

pnpm wrangler secret put NEXT_PUBLIC_SUPABASE_URL
pnpm wrangler secret put NEXT_PUBLIC_SUPABASE_ANON_KEY
pnpm wrangler secret put TMDB_API_READ_TOKEN
pnpm wrangler secret put NEXT_PUBLIC_APP_URL

3. Update wrangler.jsonc worker name if needed.

4. Build and deploy:

pnpm deploy

5. If you want to preview the production worker locally:

pnpm preview

Project structure

• app/: routes, layouts, API handlers
• actions/: server actions for auth and library updates
• components/: reusable product UI and base UI primitives
• lib/: auth, Supabase, TMDB, formatting, validators, and data access
• supabase/: SQL migration and seed SQL
• types/: typed app and database shapes

Known limitations

• Library filtering is done in memory after loading the current user’s entries. That keeps the MVP simple, but a larger collection should move filters into SQL or an RPC.
• Search uses TMDB only.
• Library entries store only a small snapshot for filtering and posters. Rich media details come from TMDB at render time.
• User profile editing is intentionally minimal.

Future improvements

• Move library filtering/sorting to SQL for larger collections
• Add magic link auth as an alternative sign-in method
• Add richer dashboard summaries and completion history
• Add watch provider links if they are useful for your audience
• Add optimistic updates and toasts for faster perceived interactions