Hessflix

Hessflix is a movie discovery web application built with React, Vite, Redux Toolkit, and React Router. It uses The Movie Database (TMDB) API to let users search for movies, browse trending titles, and open a detailed movie page with metadata and cast information.

This project appears to have been built as a collaborative course project for CS 494, with different team members owning different pages and features.

Table Of Contents

• Project Overview
• Features
• Tech Stack
• How It Works
• Project Structure
• Routes
• Getting Started
• Environment Variables
• Available Scripts
• TMDB Integration
• State Management
• Styling
• Team Contributions
• Troubleshooting
• Future Improvements

Project Overview

Hessflix provides a simple movie-browsing experience with a few focused workflows:

• A landing page introducing the app
• A movie search page powered by Redux async state
• A trending page that displays popular movies from TMDB
• A movie detail page with poster, backdrop, overview, rating, runtime, release date, and top cast
• A lightweight about page

The application is a client-side React SPA. Routing is handled in the browser, and movie data is fetched directly from TMDB using environment-based credentials.

Features

• Search for movies by title
• View search results in a reusable movie card grid
• Browse currently trending movies
• Open dedicated detail pages for individual movies
• See a movie's:
  • title
  • tagline
  • release date
  • release year
  • runtime
  • rating
  • overview
  • cast members
• Navigate between pages with a persistent top navigation bar
• Handle loading, empty, and error states on data-driven pages

Tech Stack

• React 19 for UI rendering
• Vite 7 for local development and production builds
• React Router DOM 7 for client-side routing
• Redux Toolkit for search state and async fetching
• React Redux to connect Redux state to components
• TMDB API for movie data
• CSS modules by page/component file naming convention
• Tailwind CSS packages are installed, and utility classes are used on the movie detail and cast components

How It Works

App Bootstrapping

The app starts in src/main.jsx, where the root React tree is wrapped with:

• Provider for Redux store access
• BrowserRouter for route handling

The main application shell is defined in src/App.jsx, which renders the shared navbar and route map.

Search Flow

The search experience is implemented with Redux Toolkit:

1. The user types a title into the search form.
2. On submit, the page dispatches setQuery(trimmed) and searchMovies(trimmed).
3. searchMovies is an async thunk in src/store/searchSlice.js.
4. The thunk requests TMDB /search/movie.
5. Redux updates status, results, and error.
6. The Search page renders loading state, error state, no-results state, or a results grid.

Trending Flow

The trending page fetches data directly inside the component with useEffect. On mount, it requests TMDB's weekly trending movie endpoint and stores results in local component state.

Movie Detail Flow

The movie detail page reads the id route parameter and makes two requests:

• GET /movie/{id} for main movie metadata
• GET /movie/{id}/credits for cast information

The page then formats runtime, rating, year, poster, and backdrop information before rendering the detail layout.

Project Structure

final-project-hessflix/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   │   ├── CastList.jsx
│   │   ├── MovieCard.jsx
│   │   └── Navbar.jsx
│   ├── pages/
│   │   ├── About.jsx
│   │   ├── Home.jsx
│   │   ├── MovieDetail.jsx
│   │   ├── Search.jsx
│   │   └── Trending.jsx
│   ├── store/
│   │   ├── searchSlice.js
│   │   └── store.js
│   ├── App.jsx
│   ├── main.jsx
│   └── index.css
├── index.html
├── package.json
├── vite.config.js
└── README.md

Key Files

• src/App.jsx: top-level route configuration
• src/main.jsx: app entry point with Redux + router providers
• src/store/searchSlice.js: async search logic and reducer state
• src/store/store.js: Redux store setup
• src/components/MovieCard.jsx: reusable movie card UI for lists
• src/components/CastList.jsx: cast rendering block on detail page
• src/components/Navbar.jsx: persistent site navigation

Routes

Route	Page	Description
/	Home	Landing page with calls to action
/search	Search	Search movies by title
/trending	Trending	Browse trending movies from TMDB
/movie/:id	Movie Detail	View full details for a selected movie
/about	About	Basic project/about information

Getting Started

1. Clone The Repository

git clone <your-repo-url>
cd final-project-hessflix

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env file in the project root:

VITE_TMDB_API_KEY=your_tmdb_bearer_token_here

Important: despite the variable name VITE_TMDB_API_KEY, the app code sends it as a Bearer token in the Authorization header. That means this value should match the TMDB read access token format used by the app.

4. Start The Development Server

npm run dev

Then open the local Vite URL shown in your terminal, typically:

http://localhost:5173

Environment Variables

Variable	Required	Description
VITE_TMDB_API_KEY	Yes	TMDB bearer token used for authorized API requests

Because this is a Vite app, environment variables that need to be available in client-side code must begin with VITE_.

Available Scripts

In package.json:

• npm run dev starts the Vite development server
• npm run build creates a production build
• npm run preview serves the production build locally
• npm run lint runs ESLint across the project

TMDB Integration

The project uses the following TMDB endpoints:

• GET /search/movie
• GET /trending/movie/week
• GET /movie/{id}
• GET /movie/{id}/credits

TMDB image assets are loaded from:

• https://image.tmdb.org/t/p/w300 for movie cards
• https://image.tmdb.org/t/p/w500 for posters
• https://image.tmdb.org/t/p/original for backdrops
• https://image.tmdb.org/t/p/w185 for cast profile images

Reference:

• TMDB Developer Docs

State Management

Redux is currently used for the search feature.

Search Slice State

The search slice tracks:

• query
• results
• status
• error

Search Actions

• setQuery stores the active search text
• clearResults resets results and state
• searchMovies asynchronously fetches movie data from TMDB

This keeps the search page predictable and makes loading/error handling easier to manage.

Styling

The project uses a hybrid styling approach:

• Dedicated CSS files for pages and components such as Home.css, Search.css, and Navbar.css
• Utility-style classes on some components, especially the movie detail experience

This means future contributors should check both the component file and its paired stylesheet when updating UI behavior.

Team Contributions

From the existing project documentation:

Member	Area
Ryan Doering	Home, Search
Hsun-Yu Kuo	Movie Details
Bryden Takayama	Trending, About

Troubleshooting

The app loads but movie data does not appear

Check that:

• .env exists in the project root
• VITE_TMDB_API_KEY is set
• the value is a valid TMDB bearer token
• the dev server was restarted after editing .env

Search or trending requests fail

Possible causes:

• invalid or expired TMDB token
• malformed environment variable
• TMDB API rate limits or temporary downtime
• network restrictions in the current environment

Images are missing

Some TMDB entries do not include poster, backdrop, or profile images. The app already provides fallbacks in several places.

Future Improvements

• Add pagination for search results
• Add genre filters and sorting
• Add favorites or watchlist functionality
• Improve mobile responsiveness across all pages
• Standardize styling into a single approach
• Add automated tests for pages and Redux logic
• Add loading skeletons and richer error recovery