Skip to main content

​
Quick Start Guide

This guide will get you from zero to a fully functional Film Fanatic instance in under 5 minutes.

​
Prerequisites Check

Before you begin, ensure you have:
You can verify your Node.js version with node --version. Film Fanatic requires Node.js 20 or higher.

​
Installation Steps

1

Clone the Repository

Clone Film Fanatic from GitHub to your local machine:
git clone https://github.com/Swastikdan/Film-Fanatic.git
cd film-fanatic
2

Install Dependencies

Install all required packages using pnpm:
pnpm install
This will install all dependencies defined in package.json, including React 19, TanStack Start, Convex, Clerk, and more.
3

Configure Environment Variables

Create a .env.local file in the project root with the following configuration:
.env.local
# TMDB API Configuration
VITE_TMDB_ACCESS_TOKEN=your_tmdb_token_here
VITE_TMDB_API_URL=https://api.themoviedb.org/3

# Clerk Authentication (Optional for development)
VITE_CLERK_PUBLISHABLE_KEY=your_clerk_key_here
CLERK_SECRET_KEY=your_clerk_secret_here

# Convex Backend (Optional for development)
VITE_CONVEX_URL=your_convex_url_here
CONVEX_DEPLOY_KEY=your_deploy_key_here
For a quick start, you only need the TMDB credentials. Clerk and Convex can be configured later if you want authentication and cloud sync features.
4

Start Development Server

Launch the development environment:
pnpm dev
This command runs both the Vite dev server and Convex backend in parallel using npm-run-all. The application will be available at:
http://localhost:3000

​
Verify Your Setup

Once the development server starts, you should see: 
> [email protected] dev
> npm-run-all --parallel dev:vite dev:convex

> dev:vite
> vite dev --port 3000 --host

  VITE v7.1.7  ready in 892 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: http://192.168.1.100:3000/

> dev:convex
> convex dev

  ✓ Convex functions ready
If you haven’t set up Convex yet, you’ll see a warning about the missing Convex URL. The app will still run in local-only mode using localStorage.

​
Test the Application

Verify everything works by:
  1. Opening the browser at http://localhost:3000
  2. Testing search - Try searching for a movie like “Inception”
  3. Viewing details - Click on any movie/show to see the detail page
  4. Adding to watchlist - Add items to your watchlist (stored locally without auth)

​
What’s Running?

The pnpm dev command starts multiple processes:
ProcessPortPurpose
Vite Dev Server3000Frontend development server with HMR
Convex DevN/ABackend functions with hot reload
The dev server includes React DevTools, TanStack Router DevTools, and TanStack Query DevTools for debugging.

​
Common Issues

If port 3000 is occupied, you can change it in package.json:
"dev:vite": "vite dev --port 3001 --host"
Or kill the process using port 3000:
# On macOS/Linux
lsof -ti:3000 | xargs kill -9

# On Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F
Install pnpm globally:
npm install -g pnpm
Or use npx:
npx pnpm install
npx pnpm dev
Verify your TMDB access token is correct:
  1. Go to TMDB Settings
  2. Copy the “API Read Access Token” (not the API Key)
  3. Ensure it’s set as VITE_TMDB_ACCESS_TOKEN in .env.local
  4. Restart the dev server after updating environment variables
Clear the dependency cache and reinstall:
rm -rf node_modules pnpm-lock.yaml
pnpm install

​
Next Steps

Now that you have Film Fanatic running locally, you can:

Full Installation Guide

Set up Clerk authentication and Convex cloud sync

Configuration

Customize your Film Fanatic instance

Development

Learn about the codebase and contribute

API Reference

Explore hooks and backend functions

​
Development Commands

Here are the essential commands you’ll use during development: 
# Start development server (frontend + backend)
pnpm dev

# Start only frontend
pnpm dev:vite

# Start only Convex backend
pnpm dev:convex

# Type checking
pnpm check

# Linting
pnpm lint

# Format code
pnpm format

# Build for production
pnpm build

# Preview production build
pnpm vite:serve
Always run pnpm check before committing to ensure TypeScript types are valid and Biome linting passes.

Build docs developers (and LLMs) love

Get started for freeTalk to us