A web app for searching TMDB movies and TV shows, then tracking them in a personal watch list.
Current stage: early MVP with search, title details, authentication, saved collections, custom lists, ratings, reviews, and TV episode progress.
This project currently includes:
- Next.js App Router setup
- TypeScript + Tailwind CSS
- English and Simplified Chinese interface preferences
- Supabase Auth (email/password)
- Login / signup flows with in-app logout action
- SSR-friendly session handling
- TMDB-backed title search at
/search - Title detail pages at
/title/tmdb/movie/[externalId]and/title/tmdb/tv/[externalId] - Add-to-list actions from title detail pages and saved list entries
- Protected
/mypage that groups saved titles by watch status - Per-user 1-10 ratings and short reviews for saved title entries
- TV episode progress for Watching and Completed entries
- User-created custom lists with per-title assignment
- Batch copy, move, and removal actions for custom lists
- Prisma models and migrations for profiles, titles, entries, and custom lists
- Optimized TMDB image delivery through
next/image - Short-lived search caching and longer-lived title detail caching
Not implemented yet:
- Tags
- Anime-specific search or title support
Use /search to search TMDB for movies and TV shows. Search results show a poster when available, title, media type, release year, and overview. Selecting a result opens that title's detail page.
Search requires either TMDB_ACCESS_TOKEN or TMDB_API_KEY in .env.local.
Title detail pages are served from /title/tmdb/movie/[externalId] and /title/tmdb/tv/[externalId]. They load details from TMDB, show title metadata, poster art, overview, release information, and add-to-list buttons.
Signed-in users can save a title as:
- Want to Watch
- Watching
- Completed
If a user is not signed in, the add-to-list action returns an inline login prompt instead of saving.
Use /my to view saved titles. The page requires Supabase auth when Supabase environment variables are configured, then groups entries into Plan to Watch, Watching, and Completed sections sorted by recent updates.
Each saved entry can also store your private 1-10 rating and a short review.
Rating and review edits are available from the title detail page for Watching
and Completed entries. /my keeps those values as compact summaries.
TV entries in Watching or Completed can store episode progress. The title
detail page provides the editor, while /my shows a compact progress summary.
You can also create custom lists, assign saved titles to one or more lists, and use batch actions to copy, move, or remove selected titles.
If the list is empty, /my links back to /search so users can add their first title.
- Next.js
- TypeScript
- Tailwind CSS
- Supabase Auth
- Prisma
- PostgreSQL (via Supabase)
- TMDB API
app/- routes, layouts, and server actionscomponents/- reusable interface components and focused client boundarieslib/- Supabase, Prisma, TMDB, localization, and data-access helpersprisma/- database schema and migrationstypes/- shared application typesdocs/- manual smoke-test guidance
Generated Prisma client files, Next.js build output, local environment files, and installed dependencies are intentionally excluded from Git.
Before running locally, install:
- Node.js 22+ or 24 LTS
- Git
- A Supabase account/project
- A TMDB API key or access token
Optional but recommended:
- VS Code
- Prisma extension for VS Code
- ESLint extension for VS Code
Clone the repository:
git clone https://github.com/SpaceSyt/watch-tracker
cd watch-trackerCreate your local environment file:
macOS/Linux:
cp .env.local.example .env.localWindows PowerShell:
Copy-Item .env.local.example .env.localFill in .env.local with:
NEXT_PUBLIC_SUPABASE_URL- your Supabase Project URLNEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY- your Supabase Publishable KeyNEXT_PUBLIC_SUPABASE_ANON_KEY- optional fallback for older setupsDATABASE_URL- your Supabase PostgreSQL connection stringTMDB_API_KEY- your TMDB API keyTMDB_ACCESS_TOKEN- optional TMDB bearer token; used instead ofTMDB_API_KEYwhen present
Install dependencies, generate the Prisma client, and start the dev server:
npm ci
npx prisma generate
npm run devOpen http://localhost:3000.
Prisma client must be generated locally after environment setup. If you skip npx prisma generate, database-related pages may fail at runtime.
- Create a Supabase project
- Go to Connect > Session pooler
- Copy the connection string (URI)
- Use that connection string for
DATABASE_URLin.env.local
Apply the existing migrations to a development database:
npx prisma migrate devCreate a named migration only after intentionally changing
prisma/schema.prisma.
Run the project checks before handing off changes:
npm run validateFor read-only validation without generated-file writes, run:
npm run lint
npx tsc --noEmit --incremental falsenpm run validate runs ESLint and the project typecheck script. The typecheck script generates the Prisma client first, so full validation can update generated Prisma client files.
- Prisma 7 uses
prisma.config.tsfor database config - Use Session pooler if direct connection fails
- TMDB search responses are cached briefly; title details use a longer cache
- TMDB configuration and request errors are surfaced in the UI
- The account menu loads browser auth state independently; protected routes and all write operations still validate the user on the server
- Tags
- Additional entry editing beyond watch status, rating, and short review
- Anime-specific search, detail, save, and display flows
See CONTRIBUTING.md for setup, validation, and pull request expectations.
The initial internationalization foundation was contributed by Saonian07.
Do not open a public issue for a suspected vulnerability or exposed secret. Follow SECURITY.md instead.
This project is licensed under the MIT License.