A React app for discovering and browsing movies and TV shows using The Movie Database (TMDB) API. Search or filter a poster grid, then drill into full detail pages for movies, TV shows, individual episodes, and cast/crew.
Discover grid
- Toggle between Movies and TV Shows
- Search by title, or filter by year and minimum rating
- Responsive poster grid with loading skeletons and empty/error states
Movie details
- Backdrop hero with poster, score, status, runtime, and release date
- Budget and revenue
- Top cast and director, with links to person pages
TV show details
- Same hero treatment, plus season and episode counts
- Per-season episode list with air dates, runtimes, and overviews
- Episode rating heatmap across all seasons, with clickable cells that jump straight to an episode
- Season picker for browsing episode lists in place
Episode details
- Full-width still image, overview, runtime, and air date
- Detailed crew list and guest stars
- Image gallery with a keyboard-navigable lightbox (arrow keys, escape, click-to-close)
Person details
- Biography, place of birth, and profile photo
- "Known for" credits, sorted newest first, linking back into movie/TV detail pages
Cross-cutting
- Each card and detail page links out to the title's TMDB page and to a self-hosted Seerr instance for requesting media
- Consistent dark UI with a shared rating-score component used across cards, hero sections, and the heatmap
- React
- TypeScript
- React Router
- Tailwind CSS
- shadcn/ui components
- lucide-react (icons)
- TMDB API
- Node.js (v14 or later)
- npm
-
Clone the repository:
git clone https://github.com/your-username/tmdb-movie-tv-fetcher.git cd tmdb-movie-tv-fetcher -
Install dependencies:
npm install -
Copy the example file and add your TMDB credentials:
cp .env.example .env
-
Open
.envand set your TMDB API key:REACT_APP_API_KEY=your_tmdb_api_key_here REACT_APP_BASE_URL=https://api.themoviedb.org/3 REACT_APP_POSTER_BASE_URL=https://image.tmdb.org/t/p/w500 -
Start the development server:
npm start -
Open http://localhost:3000 in your browser to view the app.
- Use the toggle to switch between Movies and TV Shows on the discover page.
- Search by title, or check "Filter by Year" and/or adjust the minimum rating slider. Rating filtering is disabled while a search query is active.
- Click any poster to open its detail page in-app.
- On a TV show's page, pick a season from the sidebar to browse its episodes, or open the rating heatmap to see every season's episode scores at once and jump directly to one.
- Click a cast member, crew credit, or director to view their person page and filmography.
- Use the TMDB and Seerr icons on a card or detail page to open that title externally.
Key pieces, for orientation:
DiscoverPage/DiscoverControls— search, filters, and the poster gridMediaCard— poster card used in the discover gridMovieDetails/TvDetailView— top-level detail pages for each media typeEpisodeDetailView— single episode page, including the image galleryPersonDetailView— cast/crew member page and filmographyCastAndCrew— shared cast rail used on movie and TV detail pagesEpisodeHeatmap— per-season episode rating grid on TV show pagesImageGallery/Lightbox— episode still thumbnails and full-screen viewerDetailContainer— shared page chrome (back navigation) wrapping all detail viewsutils/api.ts— TMDB API calls and response-to-app-type mappingutils/types.ts— shared types for media summaries, details, and TMDB response shapes
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is open source and available under the MIT License.
- The Movie Database (TMDB) for providing the API
- shadcn/ui for the UI components
- Tailwind CSS for the utility-first CSS framework
- lucide-react for icons