WatchIndex

📖Introduction

WatchIndex is a modern movie and TV show discovery platform built with React and TypeScript. It demonstrates efficient server state management using TanStack Query with the TMDB API, featuring advanced search, caching strategies, and a responsive cinema-inspired design.

Open Source Project: Perfect for learning React Query patterns, API integration, and modern frontend architecture. Uses The Movie Database (TMDB) API for comprehensive media data.

✨Features

• Movie & TV Discovery with detailed information and cast profiles
• Advanced Search with real-time suggestions and filtering
• Favorites System with localStorage persistence
• Genre Browsing with advanced filtering options
• Now Playing theatrical releases and trending content
• Responsive Design optimized for all devices
• TanStack Query for efficient data caching and synchronization
• Cinema Theme with dark UI and gold accents

🛠️Tech Stack

Frontend

• React 18.3.1 - Modern React with hooks
• TypeScript 5.5.3 - Type-safe development
• Vite 5.4.1 - Fast build tool and dev server
• React Router DOM 6 - Client-side routing

💅UI & Styling

• Tailwind CSS 3.4.11 - Utility-first CSS
• shadcn/ui - High-quality React components
• Lucide React - Icon library
• Embla Carousel - Lightweight carousel

State Management & API

• TanStack Query 5.56.2 - Server state management and caching
• Axios - HTTP client for API requests
• TMDB API v3 - Movie and TV show database

🚀Getting Started

Prerequisites

• Node.js 18+
• npm or yarn
• TMDB API Key (free at themoviedb.org)

⚡Quick Start

# Clone the repository
git clone https://github.com/cjjutba/watch-index.git
cd watchindex

# Install dependencies
npm install

# Setup environment variables
cp .env.example .env

TMDB API Setup

1. Create free account at The Movie Database
2. Go to Account Settings → API
3. Request API key (choose "Developer" option)
4. Add to your .env file:

VITE_TMDB_API_KEY=your_api_key_here
VITE_TMDB_READ_ACCESS_TOKEN=your_read_access_token_here

🔧Run Development Server

npm run dev
# Open http://localhost:8080

🏗️Build for Production

npm run build
npm run preview

🌐API Integration

WatchIndex integrates with TMDB API v3 to provide:

• Movies: Popular, top-rated, upcoming, now-playing
• TV Shows: Series, seasons, episodes, cast information
• Search: Multi-type search across movies, TV shows, and people
• People: Actor/director profiles with filmographies
• Genres: Content discovery and filtering
• Images: High-quality posters, backdrops, profile photos

Key Features:

• Intelligent caching with TanStack Query
• Background data synchronization
• Optimistic updates for favorites
• Error handling and retry logic

🤝Contributing

We welcome contributions! This project is great for:

• Learning TanStack Query patterns
• Understanding API integration best practices
• Practicing TypeScript in React
• Building responsive, data-driven applications

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

🤝Ideas for Contributions

• Add user authentication and personal lists
• Implement social features (reviews, ratings)
• Add more filtering options and sorting
• Improve mobile responsiveness
• Add animation and transition effects
• Implement dark/light theme toggle
• Add accessibility improvements

👨‍💻Author

CJ Jutba - Full Stack Developer

• Portfolio: https://cjjutba.com/
• LinkedIn: https://www.linkedin.com/in/cjjutba/
• GitHub: https://github.com/cjjutba
• Email: hello@cjjutba.com

🙏Acknowledgments

• TMDB for providing comprehensive movie and TV data
• TanStack Query for powerful server state management
• shadcn/ui for beautiful React components
• Tailwind CSS for utility-first styling