gatsby-source-tmdb
Source from The Movie Database (TMDb) API (v3) in Gatsby. You can leverage any endpoint from the official documentation and pull the data directly into Gatsby's GraphQL data layer. Customize the plugin to your needs by providing customized endpoints -- read more about that in the advanced configuration section.
You can see a live preview at tmdb.lekoarts.de (Source Code).
Create your own website with gatsby-starter-tmdb.
Install
npm install gatsby-source-tmdb
Prerequisites
You'll need an API Key
and Session ID
from TMDb.
Recommendation: Save both values inside an .env
file as environment variables. Read more about env vars in Gatsby.
You can find all information on the API endpoints in the official TMDb v3 documentation.
Configure
Add the plugin to your gatsby-config.js
require("dotenv").config()
module.exports = {
plugins: [
{
resolve: "gatsby-source-tmdb",
options: {
apiKey: process.env.API_KEY,
sessionID: process.env.SESSION_ID,
}
}
]
}
The plugin is not requesting all available endpoints by default but only a selected list of endpoints. It always requests the /account
& /configuration
endpoint. Please see the documentation below if you want to change the endpoints.
Options
apiKey: string
Required option
The API key you got from TMDb.
sessionID: string
Required option
The Session ID you generated with your API key via the TMDb API.
language: string
According to the language documentation you can pass a string
code in the format of ISO-639-1 or ISO-3166-1 into this option. If set, language
will be passed as a query parameter to all requests.
region: string
According to the region documentation you can pass a string
code in the format of ISO-3166-1. If set, region
will be passed as a query parameter to all requests.
timezone: string
You can offset the day calculation, defaulting to EST. You can query the list of timezones. If set, timezone
will be passed as a query parameter to all requests.
typePrefix: string
By default, all types created by this plugin are prefixed with TMDb
. So if you query /account/{account_id}/favorite/tv
the resulting type will be TmdbAccountFavoriteTv
. This is helpful when you use multiple instances of this plugin in the same site (by using different API keys & session IDs) and want to have multiple instances of e.g. /account/{account_id}/favorite/tv
. You'd then set a typePrefix: "Second"
and the result would be SecondAccountFavoriteTv
.
downloadImages: boolean
By default, no images for e.g. poster_path
etc. are downloaded. With this setting you can globally enable the downloading of images. Under the additional localFile
field you'll be able to access the downloaded file and use it with gatsby-plugin-image
.
endpoints: Endpoint[]
With Endpoint
being:
interface Endpoint {
url: string
typeName?: string
downloadImages?: boolean
searchParams?: {
language?: string
page?: number
append_to_response?: string
region?: string
[key: string]: string
}
context?: {
[key: string]: string
}
countLimit?: number
extension?: {
url: string
}
}
This option allows you to configure the endpoints that the plugin is requesting from the TMDb API. The plugin defines some sensible defaults.
The plugin uses got
under the hood, so some options directly come from its API design. Here are the options in detail:
url: string
Required option
The GET
route from the TMDb API. You need to remove the leading slash from the URL and replace {}
(curly braces) with :
(colon). Examples:
-
/account
=>account
-
/account/{account_id}/favorite/tv
=>account/:account_id/favorite/tv
-
/movie/{movie_id}
=>movie/:movie_id
typeName: string
Similar to the typePrefix
option you can modify the name of the type here. In this case you can completely override the name though. Example:
[{
url: "account/:account_id/favorite/tv",
typeName: "FavTv",
}]
Normally this would result in TmdbAccountFavoriteTv
but in this case it would be FavTv
.
downloadImages: boolean
The behavior is the same as the global downloadImages
setting but you can individually turn on image downloading with the setting on the Endpoint
. The global setting overwrites any Endpoint
setting.
searchParams: object
You can pass any option to the endpoint here that it offers (described in the TMDb docs) via the query parameters. You can also override the defaults for a specific endpoint here that are set in the general options, e.g. language
. The Append To Response is also available.
context: object
This user data is used to modify the URL before a request. By default, the account_id
is passed to every request inside the context
. This is why you can query endpoints that use the :account_id
parameter without providing it yourself. Example:
[{
url: "tv/:tv_id",
context: {
tv_id: "66732"
}
}]
countLimit: number
Refers to got
's pagination.countLimit
option. By default 60
items are fetched.
extension: object
Unfortunately endpoints like /account/{account_id}/favorite/tv
only return shallow results for their items. You can see this difference by comparing the "Responses" of the account endpoint and the individual tv endpoint. The extension
option mitigates this issue by allowing you to define a second request that should come after the first endpoint. Example:
[{
url: "account/:account_id/favorite/tv",
extension: {
url: "tv/:tv_id",
}
}]
So during the first request to account/:account_id/favorite/tv
a list of items (each with an id
) is fetched. In a second step for each item the tv/:tv_id
endpoint is called -- the :tv_id
is defined by the respective id
from the first request.
This way the TmdbAccountFavoriteTv
type returns a list of detailed TV responses.
Advanced Configuration
Being able to customize the endpoints
option is a powerful option of this plugin. The examples below are only a subset of things as the sky is the limit!
require("dotenv").config()
module.exports = {
plugins: [
{
resolve: "gatsby-source-tmdb",
options: {
apiKey: process.env.API_KEY,
sessionID: process.env.SESSION_ID,
endpoints: [
// Query the /discover/movie endpoint for 50 movies that were released in 2021
// Sort it by popularity and name it "Top2021Movies"
{
url: `discover/movie`,
searchParams: {
language: `en-US`,
sort_by: `popularity.desc`,
year: `2021`,
},
typeName: `Top2021Movies`,
countLimit: 50,
},
// Get the information from "Stranger Things" and more details like videos & similar tv shows
{
url: "tv/:tv_id",
context: {
tv_id: "66732"
},
searchParams: {
append_to_response: "videos,similar"
}
},
// Use the search to find TV shows with "Naruto" and use the extension to get more details
// Than the search endpoint would provide. Also name it "NarutoSearch"
{
url: "search/tv",
searchParams: {
language: "en-US",
query: "Naruto"
},
typeName: "NarutoSearch",
extension: {
url: "tv/:tv_id",
}
}
]
}
}
]
}
Migration
You want to migrate to a new major version? You can read all migration guides here: https://github.com/LekoArts/gatsby-source-tmdb/blob/main/MIGRATING.md