TMDBrJS is a TypeScript library for interacting with The Movie Database (TMDB) API. It provides a clean, typed interface with automatic camelCase conversion of API responses.
- 🎯 Full TypeScript support with comprehensive type definitions
- 🔄 Automatic camelCase conversion of TMDB API responses
- 📦 ESM and CommonJS support for all JavaScript environments
- 🎬 Complete movie endpoints including popular, top-rated, and detailed movie information
- 👥 People endpoints with credits and media information
- 🔍 Advanced append_to_response support with type safety
- ⚡ Lightweight with minimal dependencies
- 🌐 Configurable language support
Important Notice:
This package is a personal project and may not be actively maintained or thoroughly documented. Use it at your own risk. Contributions are welcome, but please note that there might be limited support and updates.
- Node.js 18 or higher
- TMDB API key (get one at themoviedb.org)
# npm
npm install tmdbrjs
# yarn
yarn add tmdbrjs
# pnpm
pnpm add tmdbrjsimport { Client } from 'tmdbrjs';
const client = new Client({ apiKey: 'YOUR_API_KEY' });const client = new Client({
apiKey: 'YOUR_API_KEY',
language: 'en-US', // Optional: defaults to 'en-US'
version: '3', // Optional: API version, defaults to '3'
baseUrl: 'https://api.themoviedb.org' // Optional: custom base URL
});try {
const movie = await client.movies.getById('550');
console.log(movie.title); // Response is automatically camelCased
} catch (error) {
if (error.message === 'Invalid API key') {
console.error('Please check your API key');
} else {
console.error('Error fetching movie:', error.message);
}
}const popularMovies = await client.movies.getPopular(1); // page number (optional)const topRated = await client.movies.getTopRated();const movie = await client.movies.getById('550');
// With append_to_response (type-safe)
const movieWithCredits = await client.movies.getById('550', {
include: ['credits', 'videos', 'images', 'recommendations', 'keywords']
});const similar = await client.movies.getSimilar('550');const credits = await client.movies.getCredits('550');const popularPeople = await client.people.getPopular(1); // page number (optional)const person = await client.people.getById('287');
// With append_to_response
const personWithCredits = await client.people.getById('287', {
include: ['movieCredits', 'tvCredits', 'externalIds', 'translations'] // Note: camelCase is automatically converted
});const movieCredits = await client.people.getMovieCredits('287');const tvCredits = await client.people.getTvCredits('287');const combinedCredits = await client.people.getCombinedCredits('287');const images = await client.people.getImages('287');const movieGenres = await client.genres.movies();
const tvGenres = await client.genres.tv();const config = await client.configuration.details();
// config.images.secureBaseUrl + size + filePath builds a poster URL
const countries = await client.configuration.countries();
const languages = await client.configuration.languages();const trending = await client.trending.all('day');
const trendingMovies = await client.trending.movies('week');
const trendingTv = await client.trending.tv('day');
const trendingPeople = await client.trending.people('week');const results = await client.search.multi('Dune', { page: 1 });
const movies = await client.search.movies('The Matrix', { year: 1999 });
const tv = await client.search.tv('The Office', { firstAirDateYear: 2005 });
const people = await client.search.people('Tilda Swinton');For multi, results carry a mediaType discriminator:
const results = await client.search.multi('Foo');
for (const r of results.results) {
if (r.mediaType === 'movie') console.log(r.title);
else if (r.mediaType === 'tv') console.log(r.name);
else console.log(r.name); // person
}const popular2026 = await client.discover.movies({
sortBy: 'popularity.desc',
withGenres: [28, 12],
primaryReleaseYear: 2026,
voteAverageGte: 7,
page: 2,
});
const recentDrama = await client.discover.tv({
sortBy: 'first_air_date.desc',
withGenres: [18],
firstAirDateYear: 2025,
});Number arrays are joined with , (TMDB's AND semantics). To express OR, pass the value as a |-joined string: withGenres: '28|12'.
The library provides full TypeScript support for TMDB's append_to_response feature:
// The response type automatically includes the appended data
const movieWithExtras = await client.movies.getById('550', {
include: ['credits', 'videos', 'images', 'recommendations']
});
// TypeScript knows about the appended properties
console.log(movieWithExtras.credits.cast);
console.log(movieWithExtras.videos.results);
console.log(movieWithExtras.recommendations.results);Movies:
credits- Cast and crew informationvideos- Trailers, teasers, clipsimages- Backdrops and postersreviews- User reviewssimilar- Similar moviesrecommendations- Recommended movieskeywords- Movie keywordstranslations- Title and overview translationsreleaseDates- Release dates by countryexternalIds- External IDs (IMDb, etc.)accountStates- User's account states (favorite, rated, watchlist)
People:
movieCredits- Movie appearancestvCredits- TV show appearancescombinedCredits- All credits combinedimages- Profile imagesexternalIds- External IDs (IMDb, social media)taggedImages- Images the person is tagged intranslations- Biography translations
All API responses are automatically converted from snake_case to camelCase:
const movie = await client.movies.getById('550');
// TMDB returns: release_date, vote_average, backdrop_path
// TMDBrJS provides: releaseDate, voteAverage, backdropPath
console.log(movie.releaseDate);
console.log(movie.voteAverage);
console.log(movie.backdropPath);- Node.js >= 18
- pnpm (recommended) or npm
- TMDB API key for running tests
- Clone the repository:
git clone https://github.com/foestauf/TMDBrJS.git
cd TMDBrJS- Install dependencies:
pnpm install- Create a
.env.testfile in the root directory with your TMDB API key:
TMDB_API_KEY=your_api_key_herepnpm build # Build both ESM and CommonJS versions
pnpm dev # Watch mode for development
pnpm test # Run unit tests with coverage
pnpm test:e2e # Run end-to-end tests
pnpm lint # Run ESLint
pnpm lint:fix # Fix ESLint issues
pnpm format # Format code with Prettier
pnpm check-types # Type check without buildingThe project uses Vitest for testing. There are two types of tests:
- Unit tests:
pnpm test- End-to-end tests:
pnpm test:e2eFor e2e tests, you can provide the API key in two ways:
- Set it in the
.env.testfile - Set it as an environment variable:
TMDB_API_KEY=your_api_key_here pnpm test:e2e
- Run linting:
pnpm lint - Fix linting issues:
pnpm lint:fix - Type checking:
pnpm check-types
This project uses Conventional Commits. Use pnpm commit to commit changes with commitizen.
The project uses GitHub Actions for continuous integration. The CI pipeline:
- Runs on Node.js 22.x and 24.x
- Performs the following checks:
- Linting
- Type checking
- Unit tests
- End-to-end tests
- Coverage reporting (via Codecov)
Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request on the GitHub repository.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
pnpm test) - Run linting (
pnpm lint) - Commit your changes using conventional commits (
pnpm commit) - Push to your branch
- Open a Pull Request
TMDBrJS is licensed under the MIT License. See the LICENSE file for more information.