TMDB SDK

A complete, zero-dependency, edge-ready TypeScript client for the TMDB API v3/v4. Built with native fetch(), strict types, automatic retries, framework proxy adapters, and full LLM/AI indexing.

bun add @carlosnc/tmdb-sdk
# or npm install @carlosnc/tmdb-sdk

Why @carlosnc/tmdb-sdk?

Feature	@carlosnc/tmdb-sdk	Legacy TMDB Libraries
Runtime Dependencies	0 (Zero) — uses native fetch()	1+ (axios, node-fetch)
Environments	Universal (Node.js >= 18, Bun, Deno, Cloudflare Workers, Vercel Edge, Browser)	Node.js only
Framework Adapters	Built-in secure proxy adapters for Next.js App Router and SvelteKit	None (manual implementation)
Resilience	Built-in automatic retries with exponential backoff on 429 & 5xx	Manual error handling
AI / LLM-Friendly	Built-in llms.txt specification for AI coding tools	None
OMDb Enrichment	Optional award integration (IMDb, Rotten Tomatoes, Metacritic)	Not supported

Authentication

import { TMDBClient } from "@carlosnc/tmdb-sdk";

const client = new TMDBClient({
  accessToken: process.env.TMDB_TOKEN, // recommended
});

// or with an API key
const client2 = new TMDBClient({
  apiKey: process.env.TMDB_KEY,
});

Warning

Security Recommendation: It is highly recommended to use accessToken (Bearer token) instead of apiKey. Passing your credentials via apiKey puts them in the URL query string, which may be inadvertently logged by proxies, servers, or error tracking services. Using accessToken sends your credentials securely via HTTP headers.

Get credentials from your TMDB API settings.

Custom HTTP Adapters

The SDK uses an HttpClient interface for all requests. The default FetchAdapter uses native fetch(). Swap it out by implementing the interface:

import { type HttpClient, TMDBClient } from "@carlosnc/tmdb-sdk";

class AxiosAdapter implements HttpClient {
  async get<T>(url: string, config?: HttpRequestConfig) {
    const res = await axios.get<T>(url, { params: config?.params, headers: config?.headers, signal: config?.signal });
    return { data: res.data, status: res.status, statusText: res.statusText, headers: res.headers as Record<string, string> };
  }
  // post, put, delete similarly...
}

const client = new TMDBClient({
  accessToken: process.env.TMDB_TOKEN,
  httpClient: new AxiosAdapter(),
});

When passing a custom httpClient, auth headers/params and retry are not injected automatically — your adapter handles those itself.

Framework Adapters

Proxy TMDB API requests through your own server to keep your token server-side.

SvelteKit

// src/routes/api/tmdb/[...path]/+server.ts
import { createSvelteKitHandler } from "@carlosnc/tmdb-sdk/sveltekit";
import { TMDB_TOKEN } from "$env/static/private";

const tmdb = createSvelteKitHandler({ token: TMDB_TOKEN });

export const GET  = tmdb;
export const POST = tmdb;
export const PUT = tmdb;
export const PATCH = tmdb;
export const DELETE = tmdb;

curl http://localhost:5173/api/tmdb/movie/550

Next.js (App Router)

// app/api/tmdb/[...path]/route.ts
import { createNextJsHandler } from "@carlosnc/tmdb-sdk/nextjs";

const tmdb = createNextJsHandler({ token: process.env.TMDB_TOKEN! });

export const GET  = tmdb;
export const POST = tmdb;
export const PUT = tmdb;
export const PATCH = tmdb;
export const DELETE = tmdb;

curl http://localhost:3000/api/tmdb/movie/550

Both adapters forward query parameters, set the Authorization: Bearer header, and surface TMDB's Cache-Control on GET responses.

Quick Start

const client = new TMDBClient({ accessToken: process.env.TMDB_TOKEN });

// System config
const config = await client.configuration.getDetails();

// Account
const account = await client.account.getDetails();

// Movie details
const movie = await client.movie.getDetails(550);

// TV series with season
const season = await client.tv.getSeasonDetails(1399, 1);

// Search
const results = await client.search.getMovies({ query: "Matrix" });

// Watch providers
const regions = await client.watchProviders.getAvailableRegions();

Movie Example

const client = new TMDBClient({ accessToken: process.env.TMDB_TOKEN });

const movie = await client.movie.getDetails(550);

console.log("Title:", movie.title);
console.log("Tagline:", movie.tagline);
console.log("Release Date:", movie.release_date);
console.log("Runtime:", movie.runtime, "mins");
console.log("Genres:", movie.genres?.map((g) => g.name).join(", "));
console.log("Overview:", movie.overview);

Examples

Browse runnable examples in the examples/ directory:

File	Demonstrates
account.ts	Account details, favorites, watchlist
authentication.ts	API key validation, request tokens, guest sessions
certification.ts	Movie and TV certifications by country
collection.ts	Collection details, images, translations
company.ts	Production company details, logos, alternative names
configuration.ts	API config, image URL builder, countries, languages
credit.ts	Credit lookup by credit ID
discover.ts	Movie and TV discovery with filters
find.ts	External ID lookup (IMDb, TVDB, etc.)
genre.ts	Movie and TV genre lists
keyword.ts	Keyword details and associated movies
movie.ts	Movie details with append_to_response
pagination.ts	Page-by-page and auto-pagination
person.ts	Popular people, details, combined credits
review.ts	Review details by review ID
search.ts	Movie, multi, and person search
trending.ts	Trending movies, TV, and people
tv-series.ts	TV series and season details
watch-providers.ts	Available regions, streaming providers

bun --env-file=.env run examples/movie.ts

Namespaces

Client	Key Methods
client.account	favorites, watchlist, ratings, lists
client.accountV4	v4 favorites, watchlist, rated, lists
client.authV4	v4 request token, access token, logout
client.authentication	sessions, request tokens, guest sessions, key validation
client.certification	movie and TV certifications
client.changes	movie, TV, and person change log
client.collection	collection details, images, translations
client.credit	credit details by ID
client.company	company details, alternative names, images
client.configuration	API and image configuration
client.discover	movie and TV discovery with filters
client.find	find by external IDs
client.genre	movie and TV genre lists
client.guestSession	guest session rated movies/TV/episodes
client.keyword	keyword details and movies
client.list	create, read, update, delete lists
client.listV4	v4 list CRUD and item management
client.movie	details, credits, images, videos, ratings, watch providers, recommendations, similar, and more
client.network	network details and alternative names
client.person	details, credits, external IDs, images, tagged images, changes
client.review	review details
client.search	multi, movie, TV, person, collection, company, keyword
client.trending	trending movies, TV, people (day/week)
client.tv	series, season, and episode details, credits, images, videos, ratings, watch providers, episode groups, and more
client.watchProviders	available regions, movie providers, TV providers

Development

# Install dependencies
bun install

# Run tests (mocked by default; set TMDB_TOKEN for live API tests)
bun test

# Type-check
bun run typecheck

# Run examples (requires TMDB_TOKEN in .env or --env-file)
bun --env-file=.env run examples/movie.ts

# Generate API documentation
bun run docs

Project Structure

src/
├── client.ts            # TMDBClient — wires all sub-clients
├── index.ts             # Barrel exports
├── client/              # One directory per namespace
│   ├── account/
│   ├── account-v4/
│   ├── auth-v4/
│   ├── authentication/
│   ├── certification/
│   ├── changes/
│   ├── collection/
│   ├── company/
│   ├── configuration/
│   ├── credit/
│   ├── discover/
│   ├── find/
│   ├── genre/
│   ├── guest-session/
│   ├── keyword/
│   ├── list/
│   ├── list-v4/
│   ├── movie/
│   ├── network/
│   ├── person/
│   ├── review/
│   ├── search/
│   ├── trending/
│   ├── tv/
│   └── watch-providers/
└── types/               # TypeScript interfaces for every endpoint

Resources

• TMDB API Reference — Getting Started
• TMDB API Docs — Getting Started
• TMDB API v3 vs v4 Comparison

---

Carlos Costa @ 2026