👋 Next.js Conf 2024: Come build, party, run, and connect with us! See all events

Client API CDN configuration

Sanity provides a CDN-distributed, cached API that is faster and cheaper to use if you are exposing the API to end-users. If you are building static sites you should use the live API to ensure you always get the freshest version.

A full explanation of the differences between these APIs is outlined in the API CDN documentation.

The Sanity JavaScript client can be configured to use either the API CDN or the API by setting the useCdn option to true or false, respectively, when configuring the client:

import sanityClient from '@sanity/client'

const client = sanityClient({
  projectId: 'your-project-id',
  dataset: 'your-dataset',
  apiVersion: '2022-08-12',
  useCdn: true
})

Protip

In most cases, we recommend setting your apiVersion to today's date. This ensures you get the most recent bugfixes and improvements, and if it works today it will continue to work tomorrow.

Note that the client will automatically fall back to using the live API in the following scenarios:

  • When a mutation is performed (create/edit/delete).
  • When listeners are used (subscribing to changes).

Gotcha

Prior to v3.0.0 of the JavaScript Client, the API CDN could not be used in combination with a token (i.e., on private datasets or to query documents on a non-root path)—setting both would ignore useCdn: true and fall back on the live API.

Versions 3.0.0 and later of the JavaScript Client remove this limitation, allowing you to specify a token and useCdn: true together to make authenticated queries to the API CDN.

Was this article helpful?