@vo1x/tmdb

@vo1x/tmdb

A TypeScript SDK for The Movie Database (TMDb) API v3

Type-safe • Modern • Lightweight

This product uses the TMDb API but is not endorsed or certified by TMDb.

Features

• Type-Safe: Automatically generated types from the TMDb OpenAPI spec ensure your code is correct.
• Modern: Uses modern JavaScript (ES2022) and works in Node.js 18+ and browsers with native fetch.
• Lightweight: Minimal dependencies and tree-shakeable to keep your project lean.
• Comprehensive: Covers all major endpoints: movies, TV, search, trending, and configuration.
• Clean Errors: Provides structured, useful errors for easier debugging.

Installation

# npm
npm install @vo1x/tmdb

# pnpm
pnpm add @vo1x/tmdb

# yarn
yarn add @vo1x/tmdb

Quick Start

import { TMDB } from "@vo1x/tmdb";

const tmdb = new TMDB({
  apiKey: process.env.TMDB_API_KEY!, // Get a key at [https://www.themoviedb.org/settings/api](https://www.themoviedb.org/settings/api)
});

// Get movie details
const movie = await tmdb.movies.get(550); // Fight Club
console.log(`${movie.title} (${movie.releaseDate}) - ${movie.voteAverage}/10`);

// Search for movies
const searchResults = await tmdb.search.movies("inception");
console.log(`Found ${searchResults.totalResults} movies.`);

API Reference

Movies

// Get movie details
const movie = await tmdb.movies.get(550, { language: "en-US" });

// Get credits
const credits = await tmdb.movies.credits(550);

// Get images
const images = await tmdb.movies.images(550);

// Get recommendations and similar movies
const recommendations = await tmdb.movies.recommendations(550);
const similar = await tmdb.movies.similar(550);

TV Shows

// Get TV show details
const show = await tmdb.tv.get(1399); // Game of Thrones

// Get credits, images, recommendations, etc.
const credits = await tmdb.tv.credits(1399);
const images = await tmdb.tv.images(1399);

Search

// Search for movies, TV shows, or people
const movies = await tmdb.search.movies("batman", { page: 1, includeAdult: false });
const tvShows = await tmdb.search.tv("breaking bad");
const people = await tmdb.search.people("leonardo dicaprio");

// Search across all types
const results = await tmdb.search.multi("marvel");

Trending

// Get daily or weekly trending content
const dailyTrending = await tmdb.trending.daily();
const weeklyTrending = await tmdb.trending.weekly();

Configuration

// Get API configuration, countries, languages, etc.
const config = await tmdb.configuration.get();
const countries = await tmdb.configuration.countries();

Person

// Get person details
const person = await tmdb.person.get(287); // Christian Bale

// Get images and combined credits
const images = await tmdb.person.images(287);
const credits = await tmdb.person.combinedCredits(287);

Error Handling

The SDK throws a TMDBError for API or network issues.

import { TMDB, TMDBError } from "@vo1x/tmdb";

try {
  await tmdb.movies.get(999999999); // Invalid ID
} catch (error) {
  if (error instanceof TMDBError) {
    console.error(`Error ${error.status}: ${error.message}`);
    // error.code contains the TMDb-specific error code
  }
}

Examples

The examples/ directory contains more detailed examples for each module.

Running Examples

# Run a specific example
pnpm example:movie

# Or run with your API key
TMDB_API_KEY=your_api_key pnpm example:movie

Configuration Options

const tmdb = new TMDB({
  apiKey: "your_api_key",     // Required
  baseUrl?: "custom_url",     // Optional
  language?: "en-US",         // Optional
});

Contributing

Contributions are welcome. Feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License.