Installation Guide

This comprehensive guide covers everything you need to set up Film Fanatic with all features enabled, including authentication and cloud synchronization.

Prerequisites

Required Software

Node.js 20+

Film Fanatic requires Node.js version 20 or higher.Download: nodejs.orgVerify installation:

node --version
# Should output v20.0.0 or higher

pnpm Package Manager

Film Fanatic uses pnpm for dependency management.Install pnpm:

npm install -g pnpm

Verify installation:

pnpm --version

pnpm is faster and more disk-efficient than npm or yarn, making it ideal for large projects.

Git

Required for cloning the repository.Download: git-scm.comVerify installation:

git --version

Required API Keys and Accounts

TMDB API Access Token (Required)

The Movie Database (TMDB) provides all movie and TV show data.Setup Steps:

Create a free account at themoviedb.org
Navigate to Settings → API
Request an API key (select “Developer” for non-commercial use)
Copy the API Read Access Token (v4 auth, not the v3 API Key)

The access token is a long Bearer token that starts with eyJ. This is different from the shorter v3 API key.

Convex Account (Optional for development)

Convex powers the real-time backend and cloud sync.Setup Steps:

Sign up at convex.dev
Create a new project
Run npx convex dev in your project to link it
Copy the deployment URL and deploy key from the dashboard

Without Convex, the app works in local-only mode using localStorage. Convex is needed for:

User authentication sync
Cross-device watchlist synchronization
Real-time updates

Clerk Account (Optional for development)

Clerk provides secure authentication and user management.Setup Steps:

Sign up at clerk.com
Create a new application
Choose your authentication methods (Email, Google, etc.)
Copy the publishable key and secret key from the dashboard
Configure the Clerk issuer URL in Convex settings

Clerk and Convex must be configured together for authentication to work. The Clerk issuer URL must match your Convex domain.

Installation Process

Step 1: Clone the Repository

Clone Film Fanatic from the official GitHub repository:

git clone https://github.com/Swastikdan/Film-Fanatic.git
cd film-fanatic

Step 2: Install Dependencies

Install all required npm packages:

pnpm install

This installs:

Framework: TanStack Start, React 19, Nitro
Backend: Convex client and React Query integration
Auth: Clerk React SDK
UI: Tailwind CSS 4.0, Radix UI, shadcn/ui components
Dev tools: Biome, TypeScript, Vite

The first installation may take 2-3 minutes depending on your internet connection.

Step 3: Environment Configuration

Create a .env.local file in the project root with your API keys and configuration:

# TMDB API Configuration
VITE_TMDB_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiJ9.your_actual_token_here
VITE_TMDB_API_URL=https://api.themoviedb.org/3

# Clerk Authentication
VITE_CLERK_PUBLISHABLE_KEY=pk_test_your_key_here
CLERK_SECRET_KEY=sk_test_your_secret_here

# Convex Backend
VITE_CONVEX_URL=https://your-project.convex.cloud
CONVEX_DEPLOY_KEY=prod:your-project|your_deploy_key_here

# Convex + Clerk Integration
CONVEX_CLERK_ISSUER_URL=https://your-clerk-domain.clerk.accounts.dev

Never commit .env.local to version control. It’s already included in .gitignore.

Step 4: Set Up Convex (Optional)

If you’re using Convex for backend functionality:

# Initialize Convex in your project
npx convex dev

This will:

Prompt you to log in to Convex
Link your local project to your Convex deployment
Deploy the schema and functions from the /convex directory
Start watching for changes

The Convex dev server will output your VITE_CONVEX_URL. Copy this to your .env.local file.

Step 5: Configure Clerk + Convex Integration (Optional)

If using both Clerk and Convex:

In Clerk Dashboard:
- Go to your application settings
- Copy your issuer URL (usually https://<your-domain>.clerk.accounts.dev)

In .env.local:

CONVEX_CLERK_ISSUER_URL=https://your-domain.clerk.accounts.dev

In Convex Dashboard:
- Go to Settings → Environment Variables
- Add CLERK_ISSUER_URL with the same value

The integration is configured in convex/auth.config.ts:

export default {
  providers: [
    {
      domain: process.env.CONVEX_CLERK_ISSUER_URL,
      applicationID: "convex",
    },
  ],
};

Step 6: Start Development

Launch the full development environment:

pnpm dev

This runs two processes in parallel:

Vite dev server on http://localhost:3000 (frontend)
Convex dev (backend functions with hot reload)

You should see output similar to:

> npm-run-all --parallel dev:vite dev:convex

VITE v7.1.7  ready in 1203 ms
➜  Local:   http://localhost:3000/
➜  Network: http://192.168.1.100:3000/

Convex functions deployed

Project Structure Overview

Understanding the codebase structure:

film-fanatic/
├── convex/                   # Backend (Convex)
│   ├── _generated/           # Auto-generated Convex code
│   ├── auth.config.ts        # Clerk authentication config
│   ├── schema.ts             # Database schema
│   ├── users.ts              # User management functions
│   └── watchlist.ts          # Watchlist mutations/queries
│
├── src/                      # Frontend (React)
│   ├── components/           # UI components
│   │   ├── ui/              # shadcn/ui base components
│   │   └── ...              # Feature-specific components
│   ├── hooks/               # Custom React hooks
│   ├── lib/                 # Utilities and clients
│   ├── routes/              # TanStack Router pages
│   ├── constants.ts         # App constants
│   ├── types.d.ts           # TypeScript type definitions
│   └── styles.css           # Global Tailwind styles
│
├── public/                   # Static assets
├── .env.local               # Environment variables (create this)
├── package.json             # Dependencies and scripts
├── tsconfig.json            # TypeScript configuration
├── vite.config.ts           # Vite build configuration
└── biome.json              # Biome linter/formatter config

Database Schema

Film Fanatic uses Convex with the following schema (defined in convex/schema.ts):

Users Table

users: {
  tokenIdentifier: string,
  name?: string,
  image?: string,
  email?: string
}

Watch Items Table

watch_items: {
  userId: Id<"users">,
  tmdbId: number,
  mediaType: "movie" | "tv",
  inWatchlist?: boolean,
  progressStatus?: "want-to-watch" | "watching" | "finished",
  reaction?: "loved" | "liked" | "mixed" | "not-for-me",
  progress?: number,  // 0-100
  title?: string,
  image?: string,
  rating?: number,
  release_date?: string,
  overview?: string,
  updatedAt: number
}

Episode Progress Table

episode_progress: {
  userId: Id<"users">,
  tmdbId: number,
  season: number,
  episode: number,
  isWatched: boolean,
  updatedAt: number
}

Build for Production

When you’re ready to deploy:

# Type check and build
pnpm build

This will:

Run TypeScript type checking
Build the Vite bundle with optimizations:
- Terser minification
- Code splitting (vendor, tanstack, convex, clerk chunks)
- Tree shaking
- Console removal in production

The build output is in .output/ directory.

Troubleshooting

Convex deployment fails

Issue: npx convex dev fails with authentication errorsSolutions:

Ensure you’re logged in: npx convex login
Check your Convex dashboard has the correct project
Verify CONVEX_DEPLOY_KEY in .env.local matches your project
Try npx convex dev --once to force a single deployment

Clerk authentication not working

Issue: Sign in/up buttons don’t work or return errorsSolutions:

Verify both VITE_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY are set
Check that your Clerk application is in development mode
Ensure CONVEX_CLERK_ISSUER_URL matches your Clerk domain exactly
Restart the dev server after changing environment variables
Check Clerk dashboard → Sessions → Settings for allowed domains

TMDB images not loading

Issue: Movie posters and images show broken image placeholdersSolutions:

Verify VITE_TMDB_ACCESS_TOKEN is the v4 Read Access Token (not v3 API key)
Check the token hasn’t expired
Ensure VITE_TMDB_API_URL=https://api.themoviedb.org/3 is set correctly

Test the API directly:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.themoviedb.org/3/movie/popular

TypeScript errors on build

Issue: pnpm build fails with TypeScript errorsSolutions:

Run pnpm check to see all type errors
Ensure all dependencies are installed: pnpm install
Clear TypeScript cache: rm -rf node_modules/.vite
Check tsconfig.json is correctly configured
Update TypeScript: pnpm add -D typescript@latest

Port conflicts

Issue: Port 3000 is already in useSolutions:

Change the port in package.json:

"dev:vite": "vite dev --port 3001 --host"

Or kill the process using port 3000:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Module resolution errors

Issue: Import errors like Cannot find module '@/components/...'Solutions:

Verify tsconfig.json has the path alias:
```
"paths": {
  "@/*": ["./src/*"]
}
```
Check vite.config.ts includes vite-tsconfig-paths plugin
Restart your IDE/editor TypeScript server
Clear cache: rm -rf node_modules/.vite

Development Scripts Reference

All available npm scripts from package.json:

Command	Description
`pnpm dev`	Start both Vite and Convex dev servers in parallel
`pnpm dev:vite`	Start only the Vite frontend dev server (port 3000)
`pnpm dev:convex`	Start only the Convex backend dev server
`pnpm build`	Type check and build for production
`pnpm serve`	Build and start production server
`pnpm vite:serve`	Preview production build locally
`pnpm format`	Format code with Biome
`pnpm lint`	Lint code with Biome (max 20 diagnostics)
`pnpm lint:fix`	Auto-fix linting issues
`pnpm check`	Run Biome check and TypeScript type checking
`pnpm check:fix`	Auto-fix all checkable issues

Run pnpm check before every commit to ensure code quality.

Next Steps

Configuration

Customize themes, features, and settings

Development Guide

Learn about the codebase architecture

API Integration

Working with TMDB and Convex APIs

Configuration

Configure environment variables and services

Get Started

Core Features

Configuration

Development

Installation

Installation Guide

Prerequisites

Required Software

Required API Keys and Accounts

Installation Process

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Environment Configuration

Step 4: Set Up Convex (Optional)

Step 5: Configure Clerk + Convex Integration (Optional)

Step 6: Start Development

Project Structure Overview

Database Schema

Users Table

Watch Items Table

Episode Progress Table

Build for Production

Troubleshooting

Development Scripts Reference

Next Steps

Configuration

Development Guide

API Integration

Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Development

​Installation Guide

​Prerequisites

​Required Software

​Required API Keys and Accounts

​Installation Process

​Step 1: Clone the Repository

​Step 2: Install Dependencies

​Step 3: Environment Configuration

​Step 4: Set Up Convex (Optional)

​Step 5: Configure Clerk + Convex Integration (Optional)

​Step 6: Start Development

​Project Structure Overview

​Database Schema

​Users Table

​Watch Items Table

​Episode Progress Table

​Build for Production

​Troubleshooting

​Development Scripts Reference

​Next Steps

Configuration

Development Guide

API Integration

Configuration

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Required Software

Required API Keys and Accounts

Installation Process

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Environment Configuration

Step 4: Set Up Convex (Optional)

Step 5: Configure Clerk + Convex Integration (Optional)

Step 6: Start Development

Project Structure Overview

Database Schema

Users Table

Watch Items Table

Episode Progress Table

Build for Production

Troubleshooting

Development Scripts Reference

Next Steps