Versión en Español

🎬 CineDB

    

A modern web application to explore popular movies, search for detailed information, and discover new titles. CineDB utilizes The Movie Database (TMDB) API to provide a complete cinematic browsing experience with real-time updated data.

🔄 Migration Completed: This project was successfully migrated from IMDB web scraping to TMDB API (January 2026).

✨ Features

• 🏆 Top 20 Popular Movies: View the most popular movies of the moment according to TMDB.
• 🎬 Discovery Categories:
  • Top Rated: Top movies with the highest rating on TMDB.
  • Now Playing: Movies currently in theaters.
  • Upcoming: Future releases.
• 🎭 Genre Filters: Discover movies by categories (Action, Comedy, Drama, Horror, Sci-Fi, Romance, Thriller).
• 🔍 Instant Search: Search for movies by title with real-time results.
• 📊 Detailed Information: Access comprehensive info including:
  • Synopsis and ratings (TMDB ratings).
  • Director, writers, and full cast.
  • Duration, release year, and genres.
  • Integrated YouTube trailers.
  • User vote count.
  • Recommended movies based on the current title.
  • Similar movies with a horizontal carousel.
• 📱 Responsive Design: Optimized for mobile, tablet, and desktop devices.
• 🎨 Modern Interface:
  • Dark design with amber/gold gradient accents.
  • glassmorphism Navbar with backdrop-blur.
  • Horizontal carousels with smooth scroll.
  • Optimized skeleton loaders during loading.
  • Elegant custom scrollbar.
  • Sticky footer.
  • Hover effects with smooth transitions.
• ⚡ Optimized Performance: Built with Next.js 16 and Turbopack.
• 🌐 Content in Spanish: Data automatically translated by TMDB.

📸 Gallery

Category Exploration

Full Details

Quick Search

🛠️ Technologies Used

Frontend

• Next.js 16.1.1 - React Framework with App Router.
• React 19.2.3 - UI Library.
• TypeScript 5.9.3 - Static typing for JavaScript.
• Tailwind CSS 4.1.18 - Utility-first CSS framework with custom gradients.
• Lucide React - Modern and accessible icons.

Backend & APIs

• Next.js API Routes - Server-side endpoints as a proxy.
• TMDB API (v3) - Official Movie Database API.
• Fetch API - Native HTTP requests (no external libraries).

Development Tools

• ESLint 9 - Code linting.
• pnpm 10.13.1 - Fast and efficient package manager.
• Turbopack - Next-generation bundler.

🚀 Installation and Setup

Prerequisites

• Node.js 20+ installed (Download here)
• pnpm installed globally:

  npm install -g pnpm

• TMDB Account (free) to obtain an API Key.

---

🔑 Step 1: Obtain your TMDB API Key

1. Create an account on TMDB (if you don't have one):

   • Go to https://www.themoviedb.org/signup
   • Complete the registration (avoid using a Gmail account if possible to prevent 403 errors).

2. Request API Access:

   • Log in to TMDB.
   • Go to your profile → Settings → API.
   • Click on "Create" or "Request an API Key".
   • Select "Developer" (non-commercial).
   • Complete the basic form.
   • Accept the terms of use.

3. Copy the Read Access Token (v4):

   • Once approved, you will see two tokens.
   • Important: Copy the "API Read Access Token (v4 auth)".
   • This is a long Bearer token (starts with eyJ...).
   • DO NOT use the "API Key (v3 auth)".

---

📦 Step 2: Clone and Install

# 1. Clone the repository
git clone https://github.com/YeralAndre/cine-db.git
cd cine-db

# 2. Install dependencies
pnpm install

# 3. Create environment variables file
cp .env.example .env.local

---

⚙️ Step 3: Configure Environment Variables

Open the .env.local file and add your API Key:

# .env.local
TMDB_API_KEY=your_complete_bearer_token_here

⚠️ Important: NEVER share your API Key publicly or upload it to GitHub. The .env.local file is already in .gitignore.

---

跑 Step 4: Run the Project

# Development mode
pnpm dev

Open http://localhost:3000 in your browser.

---

🔒 Security

• ✅ Server-side API Key: The TMDB key is only used in API Routes (server-side).
• ✅ No client exposure: Browser JavaScript never sees the API key.
• ✅ Rate limiting: TMDB allows 1,000,000 requests/month on the free plan.
• ✅ HTTPS: Vercel provides automatic SSL.

📁 Project Structure

cine-db/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── page.tsx           # Main page (Top movies + genre filters)
│   │   ├── layout.tsx         # Main layout with Navbar and Footer
│   │   ├── globals.css        # Global styles (gradients, scrollbar)
│   │   ├── api/               # API Routes (Server-side)
│   │   │   └── movies/        # Movie endpoints
│   │   │       ├── top/       # GET /api/movies/top
│   │   │       ├── top-rated/ # GET /api/movies/top-rated
│   │   │       ├── now-playing/ # GET /api/movies/now-playing
│   │   │       ├── upcoming/  # GET /api/movies/upcoming
│   │   │       ├── search/    # GET /api/movies/search?q={query}
│   │   │       ├── info/      # GET /api/movies/info?id={movieId}
│   │   │       ├── discover/  # GET /api/movies/discover?with_genres={id}
│   │   │       ├── recommendations/ # GET /api/movies/recommendations?id={movieId}
│   │   │       └── similar/   # GET /api/movies/similar?id={movieId}
│   │   ├── search/            # Search page
│   │   │   └── page.tsx       # /search
│   │   └── info/[id]/         # Details page
│   │       └── page.tsx       # /info/{id}
│   ├── components/            # Reusable components
│   │   ├── Navbar.tsx         # glassmorphism navigation bar
│   │   ├── Footer.tsx         # Sticky footer
│   │   ├── TopCard.tsx        # Popular movie card with hover effects
│   │   ├── MoviesCard.tsx     # Compact card for carousels
│   │   ├── MoviesInfoSections.tsx # Horizontal carousel section
│   │   ├── GenreFilterCard.tsx # Genre filter chip
│   │   └── Loading.tsx        # Loading spinner
│   ├── lib/                   # Business logic
│   │   ├── api.ts            # ⭐ TMDB API Client (core) with 9 endpoints
│   │   └── fetchAPI.ts       # Internal API Client
│   ├── types/                 # TypeScript Interfaces
│   │   ├── movies.d.ts       # Movie, QueryMovie, InfoMovie
│   │   └── images.d.ts       # Types for importing images
│   └── assets/               # Static resources
│       ├── placeholder.png   # Placeholder image
│       └── logo.png          # CineDB Logo
├── public/                   # Static public files
├── .env.example             # Env variables template
├── package.json             # Dependencies and scripts
├── next.config.ts          # Next.js configuration
├── postcss.config.mjs      # PostCSS configuration
└── tsconfig.json          # TypeScript configuration

🔧 Available Scripts

# Development with Turbopack (hot reload)
pnpm dev

# Production build
pnpm build

# Run production build
pnpm start

# Code linting
pnpm lint

🎯 API Endpoints

Internal Endpoints (Next.js API Routes)

These endpoints are consumed by the frontend:

GET /api/movies/top
└── Returns: Movie[]
    └── TMDB Top 20 popular movies

GET /api/movies/top-rated
└── Returns: Movie[]
    └── Highest rated movies

GET /api/movies/now-playing
└── Returns: Movie[]
    └── Movies currently in theaters

GET /api/movies/upcoming
└── Returns: Movie[]
    └── Upcoming movie releases

GET /api/movies/discover?with_genres={genreId}&sort_by=popularity.desc&language=es-ES
└── Returns: Movie[]
    └── Movies filtered by genre
    └── Example: /api/movies/discover?with_genres=28 (Action)

GET /api/movies/search?q={query}
└── Returns: QueryMovie[]
    └── Search results by title

GET /api/movies/info?id={movieId}
└── Returns: InfoMovie
    └── Full info: details + trailer + credits

GET /api/movies/recommendations?id={movieId}
└── Returns: Movie[]
    └── Recommended movies based on TMDB algorithm

GET /api/movies/similar?id={movieId}
└── Returns: Movie[]
    └── Similar movies by genre and keywords

TMDB API (Backend)

The src/lib/api.ts file consumes these TMDB endpoints:

GET https://api.themoviedb.org/3/movie/popular
└── Used by: topMovies()

GET https://api.themoviedb.org/3/movie/top_rated
└── Used by: topRated()

GET https://api.themoviedb.org/3/movie/now_playing
└── Used by: nowPlaying()

GET https://api.themoviedb.org/3/movie/upcoming
└── Used by: upcoming()

GET https://api.themoviedb.org/3/discover/movie?with_genres={id}
└── Used by: discoverMovies()

GET https://api.themoviedb.org/3/search/movie?query={q}
└── Used by: searchMovies()

GET https://api.themoviedb.org/3/movie/{id}?append_to_response=videos,credits
└── Used by: infoMovie()

GET https://api.themoviedb.org/3/movie/{id}/recommendations
└── Used by: recommendedMovies()

GET https://api.themoviedb.org/3/movie/{id}/similar
└── Used by: similarMovies()

---

🎨 Design and UX

Color Palette

• Main Background: Dark Gray (gray-950, #030712)
• Primary Accent: Amber/Gold Gradient (#fbbf24 → #d97706)
• Text: White and Grays (gray-100, gray-300, gray-400)
• Cards: Medium Gray (gray-800, gray-900)
• Borders: Translucent grays with amber hover.
• Navbar: glassmorphism with backdrop-blur-sm and bg-gray-950/80.

Typography

• Main Font: Inter (Google Fonts).
• Adaptable sizes based on viewport.
• Weights: Light (300), Regular (400), Medium (500), Semibold (600), Bold (700), ExtraBold (800).

Effects and Animations

• Custom Gradients:
  • .text-gradient: Amber gradient text (for titles).
  • .bg-gradient: Amber gradient background (for buttons/badges).
• Custom Scrollbar:
  • 8px width, gray-600 color with gray-500 hover.
  • Compatible with WebKit and Firefox.
• Hover States:
  • Cards with amber border and elevation.
  • Genres with translucent amber background.
  • Smooth transitions of 200-250ms.
• Loading States: Animated spinner with rotation.
• glassmorphism: Navbar with frosted glass effect.

Responsive Layout

• Mobile First: Optimized for small screens.
• Adaptable Grid: Changes at md, lg, xl breakpoints.
• Sticky Footer: Always at the bottom with flex-1 on main.
• Horizontal Carousels: With smooth scroll and custom scrollbar.

---

📊 TypeScript Interfaces

Movie (Main)

interface Movie {
  id?: string;
  poster?: string;
  top?: string; // Ranking position
  title?: string;
  year?: string;
  rating?: string; // Average rating (0-10)
  genres?: string[]; // Genre array
  overview?: string; // Synopsis
  adult?: boolean; // +18 Rating
}

Usage: Popular, Discover, Recommendations, Similar

QueryMovie

interface QueryMovie {
  id?: string;
  poster?: string;
  title?: string;
  year?: string;
  type?: string; // "movie"
  authors?: string[]; // Director array (optional)
}

Usage: Search results

InfoMovie

interface InfoMovie {
  id?: string;
  title?: string;
  originalTitle?: string;
  year?: string;
  category?: string; // Genres comma separated
  duration?: string; // Format "2h 18min"
  rating?: string; // TMDB rating (0-10)
  peopleRating?: string; // Vote count
  poster?: string; // Full TMDB poster URL
  tags?: string[]; // Genre array
  synopsis?: string; // Full description
  trailer?: string; // YouTube video ID for embed
  direction?: string; // Main director
  writers?: string[]; // Up to 5 writers
  actors?: string[]; // Top 10 main actors
}

Usage: Details page /info/[id]

---

🎭 Available Genres

Genre filtering system with 8 main categories:

const genres = [
  { id: null, name: "All" }, // Shows popular movies
  { id: 28, name: "Action" },
  { id: 35, name: "Comedy" },
  { id: 18, name: "Drama" },
  { id: 27, name: "Horror" },
  { id: 878, name: "Sci-Fi" },
  { id: 10749, name: "Romance" },
  { id: 53, name: "Thriller" },
];

Full TMDB Genre Mapping (available in src/lib/api.ts):

• 28: Action | 12: Adventure | 16: Animation | 35: Comedy
• 80: Crime | 99: Documentary | 18: Drama | 10751: Family
• 14: Fantasy | 36: History | 27: Horror | 10402: Music
• 9648: Mystery | 10749: Romance | 878: Science Fiction
• 10770: TV Movie | 53: Thriller | 10752: War | 37: Western

---

🔧 Advanced Configuration

Environment Variables

.env.local file:

# TMDB API Configuration
TMDB_API_KEY=your_bearer_token_here

.env.example file (for repository):

# TMDB API Configuration
# Get your API Key at: https://www.themoviedb.org/settings/api
# Use the "API Read Access Token (v4 auth)" NOT the "API Key (v3 auth)"

TMDB_API_KEY=your_tmdb_bearer_token_here

Next.js Config

The project uses standard Next.js 15 configuration with Turbopack enabled.

---

🐛 Troubleshooting

Error: "TMDB_API_KEY is not configured"

• ✅ Verify that .env.local exists.
• ✅ Ensure you are using TMDB_API_KEY (without NEXT_PUBLIC_).
• ✅ Restart the development server (pnpm dev).

Error: "HTTP error! status: 401"

• ❌ Your API Key is invalid or expired.
• ✅ Verify that you copied the complete Read Access Token (v4).
• ✅ Regenerate the token on TMDB if necessary.

Posters are not appearing

• ✅ Verify your internet connection.
• ✅ Check if TMDB is operational.
• ✅ Check the browser console for CORS errors.

Build fails on Vercel

• ✅ Ensure you added TMDB_API_KEY in Vercel Environment Variables.
• ✅ Verify that the repository has all necessary files.
• ✅ Check build logs in Vercel Dashboard.

---

📝 Changelog

v2.2.0 (January 2026) - Discovery Categories

• ✅ New movie sections: Top Rated, Now Playing, Upcoming.
• ✅ 3 new API endpoints: /api/movies/top-rated, now-playing, upcoming.
• ✅ 9 functions in api.ts: topRated(), nowPlaying(), upcoming() added.
• ✅ Optimized skeleton loaders: MoviesInfoSectionsSkeleton reduced from 519 to 45 lines (91% less code).
• ✅ Horizontal carousels: Smooth scroll with custom scrollbar in each category.
• ✅ Loading states: Independent loading states per category. ... and more.

v2.1.0 (January 2026) - Feature Update

• ✅ Genre filters: Discovery system with 8 categories.
• ✅ Recommended and similar movies: Endpoints and horizontal carousels.
• ✅ Movie Interface: Renamed from TopMovie, now more versatile.
• ✅ Custom scrollbar: Elegant design with theme colors.
• ✅ Custom gradients: .text-gradient and .bg-gradient in CSS.
• ✅ Navbar glassmorphism: Frosted glass effect with backdrop-blur.
• ✅ Sticky footer: Always at the end with flex layout.
• ✅ New components: MoviesCard, MoviesInfoSections, GenreFilterCard.
• ✅ Dependency updates: Next.js 16.1.1, React 19.2.3.
• ✅ UX improvements: Hover effects, smooth transitions, loading states.

v2.0.0 (January 2026) - TMDB Migration

• ✅ Complete migration from IMDB scraping to TMDB API.
• ✅ Removed Cheerio dependency.
• ✅ Integrated YouTube trailers.
• ✅ Full credits information (director, writers, actors).
• ✅ Real-time updated data.
• ✅ Better performance and reliability.

v1.0.0 (2024) - Initial Version

• ✅ IMDB web scraping.
• ✅ Top movies.
• ✅ Basic search.
• ✅ Detailed information.

---

🤝 Contributions

Contributions are welcome. Please:

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

---

📄 License

This project is under the MIT license. See the LICENSE file for details.

---

🙏 Credits

• The Movie Database (TMDB) - For their excellent free API.
• Next.js - Amazing framework.
• Vercel - Simplified hosting and deployment.
• Tailwind CSS - Utility-first CSS framework.
• Lucide Icons - Beautiful and consistent icons.

---

📞 Contact

Project Link: https://github.com/YeralAndre/cine-db

Live Demo: https://cine-db.vercel.app

---

⭐ If you liked the project, give it a star on GitHub ⭐

Made with ❤️ using Next.js and TMDB API