Skip to main content

Welcome to Film Fanatic Documentation

Build and customize your own media discovery platform with real-time synchronization, intelligent search, and granular tracking for movies and TV shows.

Get StartedExplore API Reference

Quick Start

Get Film Fanatic running locally in just a few steps

1

Clone and Install

Clone the repository and install dependencies with your preferred package manager.
git clone https://github.com/Swastikdan/Film-Fanatic.git
cd film-fanatic
npm install
2

Configure Environment Variables

Create a .env.local file with your API keys and service credentials.
.env.local
# TMDB API
VITE_TMDB_ACCESS_TOKEN=your_tmdb_token_here
VITE_TMDB_API_URL=https://api.themoviedb.org/3

# Clerk Authentication
VITE_CLERK_PUBLISHABLE_KEY=your_clerk_key_here
CLERK_SECRET_KEY=your_clerk_secret_here

# Convex Backend
CONVEX_DEPLOY_KEY=your_convex_key_here
VITE_CONVEX_URL=your_convex_url_here
You’ll need accounts with TMDB, Clerk, and Convex to get your API keys.
3

Start Development Server

Run both the Vite dev server and Convex backend simultaneously.
pnpm dev
This runs both vite dev and convex dev in parallel. Your app will be available at http://localhost:3000.
4

Explore the Platform

Open your browser and start exploring! Search for movies and TV shows, create your watchlist, and track your viewing progress.
Guest users can use the platform with local storage. Sign in with Clerk to enable cloud synchronization and access your watchlist from any device.

Explore Core Features

Discover what makes Film Fanatic a powerful media tracking platform

Media Discovery

Real-time search across movies, TV shows, and people with rich media context and recommendations

Watchlist Management

Hybrid local-first storage with cloud sync, supporting multiple watch statuses and reactions

Episode Tracking

Granular episode-by-episode tracking with automatic progress calculation for TV shows

Advanced Search

Multi-category search with advanced filtering by rating, type, and popularity

Development Guide

Learn about the architecture and customize Film Fanatic for your needs

🏗️

Architecture Overview

Understand the tech stack: TanStack Start, Convex backend, and React 19 with the React Compiler

Learn more
🧩

Component Library

Explore the UI components built with Radix UI primitives and styled with Tailwind CSS

Browse components
⚡

State Management

Learn how Zustand and TanStack Query work together for optimistic updates

Read guide
🛣️

File-based Routing

Understand TanStack Router’s file-based routing system and route configuration

Explore routes

API Reference

Complete documentation for hooks, backend functions, and integrations

React Hooks

Watchlist management, progress tracking, and import/export utilities

Convex Backend

Real-time mutations and queries for users, watchlists, and episodes

TMDB Integration

Cached API client for fetching movies, TV shows, and metadata

Resources & Configuration

Essential guides for configuring and deploying Film Fanatic

Environment Setup

Configure TMDB, Clerk, and Convex API keys

Authentication

Set up Clerk authentication and user management

Database Schema

Understand the Convex schema and data model

Ready to Build Your Media Platform?

Follow our quickstart guide to get Film Fanatic running in minutes, or explore the architecture to understand how everything works together.

Start BuildingView on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us