Installation

Overview

This guide provides comprehensive instructions for installing and configuring Popcorn Vision on your local development environment. By the end, you’ll have a fully functional movie and TV show discovery platform.

Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js

Version 18.17 or higherCheck your version:

node --version

Download from nodejs.org

pnpm

Version 9.15.5 (recommended)Check your version:

pnpm --version

Install globally:

npm install -g [email protected]

Git

Latest stable versionCheck your version:

git --version

Download from git-scm.com

TMDB Account

Free API accessCreate an account at themoviedb.org and request API credentials

Step-by-Step Installation

Clone the Repository

Clone Popcorn Vision from GitHub:

git clone https://github.com/fachryafrz/popcorn-vision.git
cd popcorn-vision

Fork for Development

If you plan to contribute or customize:

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/popcorn-vision.git
cd popcorn-vision

Add upstream remote:

git remote add upstream https://github.com/fachryafrz/popcorn-vision.git

Install Dependencies

Install all required packages using your preferred package manager:

pnpm install

Why pnpm? The project is configured with [email protected] as specified in package.json. It’s faster and more efficient than npm or yarn, but all three package managers are supported.

Key Dependencies

Popcorn Vision uses these major packages:

package.json

{
  "dependencies": {
    "next": "14.2.35",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "axios": "^1.12.0",
    "tailwindcss": "^3.4.17",
    "daisyui": "^3.9.4",
    "@mui/material": "^5.16.14",
    "zustand": "^4.5.6",
    "framer-motion": "^11.18.2"
  }
}

Configure Environment Variables

Create your environment configuration file:

cp .env.example .env

Required Configuration

Open .env and configure the following:

.env

# TMDB API Configuration (REQUIRED)
API_URL="https://api.themoviedb.org/3"
API_KEY="your_api_key_here"
API_READ="your_read_access_token_here"

# Image CDN URLs (pre-configured, no changes needed)
NEXT_PUBLIC_API_IMAGE_45="https://image.tmdb.org/t/p/w45"
NEXT_PUBLIC_API_IMAGE_92="https://image.tmdb.org/t/p/w92"
NEXT_PUBLIC_API_IMAGE_154="https://image.tmdb.org/t/p/w154"
NEXT_PUBLIC_API_IMAGE_185="https://image.tmdb.org/t/p/w185"
NEXT_PUBLIC_API_IMAGE_300="https://image.tmdb.org/t/p/w300"
NEXT_PUBLIC_API_IMAGE_342="https://image.tmdb.org/t/p/w342"
NEXT_PUBLIC_API_IMAGE_500="https://image.tmdb.org/t/p/w500"
NEXT_PUBLIC_API_IMAGE_632="https://image.tmdb.org/t/p/w632"
NEXT_PUBLIC_API_IMAGE_780="https://image.tmdb.org/t/p/w780"
NEXT_PUBLIC_API_IMAGE_1280="https://image.tmdb.org/t/p/w1280"
NEXT_PUBLIC_API_IMAGE_ORIGINAL="https://image.tmdb.org/t/p/original"

# Google Analytics (optional)
GA_MEASUREMENT_ID=""

Getting TMDB API Credentials

Step-by-step: Get your TMDB API keys

Create an Account
- Visit themoviedb.org
- Click “Join TMDB” to create a free account
- Verify your email address
Request API Access
- Log in and go to Settings → API
- Click “Request an API Key”
- Choose “Developer” option
Fill Out the Application
- Type of Use: Website or Personal
- Application Name: Popcorn Vision (Local Development)
- Application URL: http://localhost:3000
- Application Summary: Personal movie discovery platform
- Accept the terms and submit
Copy Your Credentials
- API Key (v3 auth): Copy to API_KEY in .env
- API Read Access Token (v4 auth): Copy to API_READ in .env

Verify Your Setup

# Test your API key
curl "https://api.themoviedb.org/3/movie/550?api_key=YOUR_API_KEY"

Security Notice: Never commit your .env file to version control. It’s already included in .gitignore to protect your API credentials.

Understanding the Configuration

The axios client is configured to use these environment variables:

src/lib/axios.js

import Axios from "axios";

export const axios = Axios.create({
  baseURL: process.env.API_URL,              // TMDB API base URL
  params: { api_key: process.env.API_KEY },  // Auto-append API key
  adapter: "fetch",                          // Use native fetch
  fetchOptions: {
    next: { revalidate: 3600 },              // Cache responses for 1 hour
  },
});

Start the Development Server

Launch the Next.js development server:

pnpm dev

Expected Output

▲ Next.js 14.2.35
- Local:        http://localhost:3000
- Network:      http://192.168.1.100:3000
- Environments: .env

✓ Ready in 2.5s
✓ Compiled in 1.2s

The server will automatically reload when you make changes to the code. This is powered by Next.js Fast Refresh.

Verify Installation

Open your browser and navigate to:

http://localhost:3000

What You Should See

Homepage Features

Hero Slider: Carousel of trending movies/TV shows with backdrop images
Now Playing: Currently available movies in theaters
Upcoming: Future releases in the next 3 months
Top Rated: Highest-rated content by vote count
Trending: Popular content this week
Company Sections: Content from major studios
Genre Sections: Horror, Comedy, Sci-Fi movies

Navigation Options

Test the API Connection

Check the browser console (F12) for any errors. A successful setup will show:

✓ Fetched trending movies
✓ Fetched now playing movies
✓ Fetched upcoming movies

Build for Production

When you’re ready to deploy:

pnpm build
pnpm start

Production Configuration

The site configuration automatically adjusts for production:

src/config/site.js

export const siteConfig = {
  name: "Popcorn Vision",
  description: "The ultimate platform for movie and TV show enthusiasts...",
  url:
    process.env.NODE_ENV === "production"
      ? "https://popcorn.fachryafrz.com"
      : "http://localhost:3000",
};

Troubleshooting

Port 3000 already in use

Error: Port 3000 is already in useSolution: Either kill the process using port 3000 or specify a different port:

# Use a different port
PORT=3001 pnpm dev

Find and kill the process:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

API requests return 401 Unauthorized

Error: Invalid API key: You must be granted a valid key.Causes:

API key is incorrect or missing in .env
.env file wasn’t copied from .env.example
Server wasn’t restarted after changing .env

Solution:

Verify your API key at TMDB Settings
Ensure .env exists and contains correct credentials

Restart the development server:

# Stop the server (Ctrl+C) then restart
pnpm dev

Images not loading

Error: Broken image placeholders or 404 errorsCauses:

Image URLs in .env are incorrect
TMDB image CDN is unreachable
Content doesn’t have poster/backdrop images

Solution:

Verify image URLs match .env.example exactly

Test direct image access:

https://image.tmdb.org/t/p/w500/[image_path]

Check browser console for CORS or network errors

pnpm: command not found

Error: bash: pnpm: command not foundSolution: Install pnpm globally:

npm install -g [email protected]

Module not found errors

Error: Module not found: Can't resolve '@/components/...'Causes:

Dependencies weren’t installed properly
Node modules are corrupted
Path aliases aren’t configured

Solution:

# Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Or with npm
rm -rf node_modules package-lock.json
npm install

The path aliases are configured in jsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Rate limiting errors

Error: 429 Too Many RequestsCause: TMDB API has rate limits (around 40 requests per 10 seconds)Solution:

Popcorn Vision implements automatic rate limiting with the limiter package
Responses are cached for 1 hour to reduce API calls
If you’re still hitting limits, consider:
- Reducing concurrent requests in development
- Implementing additional caching layers
- Upgrading to TMDB API v4 for higher limits

Next Steps

Now that you have Popcorn Vision installed:

Explore the Codebase

/src/app: Next.js App Router pages
/src/components: Reusable React components
/src/lib: Utility functions and axios client
/src/zustand: State management stores

Customize Configuration

tailwind.config.js: Styling configuration
next.config.mjs: Next.js settings
/src/config/site.js: Site metadata

Add Features

Study the component structure to add:

New search filters
User profile enhancements
Social sharing features

Contribute

Read CODE_OF_CONDUCT.md
Fork and create a feature branch
Submit pull requests on GitHub

Additional Resources

TMDB API Documentation

Official API reference for endpoints, parameters, and response formats

Next.js Documentation

Learn about Next.js 14 features, App Router, and server components

Live Demo

Experience the production version of Popcorn Vision

Get Started

Core Features

Configuration

Components

Overview

Prerequisites

Node.js

pnpm

Git

TMDB Account

Step-by-Step Installation

Fork for Development

Key Dependencies

Required Configuration

Getting TMDB API Credentials

Understanding the Configuration

Expected Output

What You Should See

Test the API Connection

Build for Production

Production Configuration

Troubleshooting

Next Steps

Explore the Codebase

Customize Configuration

Add Features

Contribute

Additional Resources

TMDB API Documentation

Next.js Documentation

Live Demo

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Components

​Overview

​Prerequisites

Node.js

pnpm

Git

TMDB Account

​Step-by-Step Installation

​Fork for Development

​Key Dependencies

​Required Configuration

​Getting TMDB API Credentials

​Understanding the Configuration

​Expected Output

​What You Should See

​Test the API Connection

​Build for Production

​Production Configuration

​Troubleshooting

​Next Steps

Explore the Codebase

Customize Configuration

Add Features

Contribute

​Additional Resources

TMDB API Documentation

Next.js Documentation

Live Demo

Build docs developers (and LLMs) love

Overview

Prerequisites

Step-by-Step Installation

Fork for Development

Key Dependencies

Required Configuration

Getting TMDB API Credentials

Understanding the Configuration

Expected Output

What You Should See

Test the API Connection

Build for Production

Production Configuration

Troubleshooting

Next Steps

Additional Resources