# How do Sanity and Next.js work together?

Reviewed by Martin Dejnicki · facts verified 25 October 2026 · canonical: https://deploi.ca/sanity/integrations/nextjs

Experience: Deploi runs this in production.

## Short answer

Sanity and Next.js connect through next-sanity, Sanity's official toolkit, whose latest release, 13.4.0, requires Next.js 16 ([npm registry](https://registry.npmjs.org/next-sanity), October 2026). It bundles the Sanity client, live content helpers, Visual Editing and an embeddable Sanity Studio ([Sanity Docs, Sanity and Next.js](https://www.sanity.io/docs/nextjs/introduction), October 2026). The live helpers are App Router only ([Sanity Docs, Query content in Next.js](https://www.sanity.io/docs/nextjs/query-content-nextjs), October 2026), so Pages Router sites run on timed regeneration and signed webhooks.

- **Official toolkit:** next-sanity 13.4.0, released 23 October 2026. Every release numbered 12.0.0 or higher declares Next.js 16 as its peer; v13 also needs React 19.2.3 or later ([npm, next-sanity package metadata](https://registry.npmjs.org/next-sanity); [Sanity Docs, Query content in Next.js](https://www.sanity.io/docs/nextjs/query-content-nextjs))
- **Live content:** defineLive and SanityLive, App Router only. Sanity's recommended fetch method; Pages Router apps use getStaticProps with revalidate instead ([Sanity Docs, Query content in Next.js](https://www.sanity.io/docs/nextjs/query-content-nextjs); [Sanity Docs, Add live content to your application](https://www.sanity.io/docs/developer-guides/live-content-guide))
- **Next.js 16 on next-sanity v12:** 4x average request increase. Worst cases ran 7 to 10x or more on sites with many segments; next-sanity v13.0.0 (21 May 2026) changes the default ([Sanity Docs, Next.js 16 and SanityLive: avoiding request overages](https://www.sanity.io/docs/help/nextjs-16-sanitylive-status))
- **Webhook limit:** 2 on Free, 4 on Growth. GROQ-powered webhooks as listed on Sanity's pricing page in October 2026, so map many document types to paths in one signed route ([Sanity, Plans that scale with you](https://www.sanity.io/pricing))

## Deploi's call

Build new Sanity sites on the Next.js App Router with next-sanity and defineLive. Keep a working Pages Router site on timed ISR, and add a signed webhook route where editors need faster updates, as deploi.ca does for its FAQ hub, but plan the Next.js 16 upgrade now: the current next-sanity requires it, and both of Sanity's Visual Editing guides are written for it.

**USE: Use next-sanity on the App Router when**

- You're starting a new Sanity build, or already on Next.js 16, which every next-sanity release numbered 12.0.0 or higher requires as of October 2026.
- Editors need click-to-edit Visual Editing in the Presentation tool.
- Visitors should see published changes without a webhook to maintain, because defineLive refreshes tagged queries from live events.
- You can stay on the current next-sanity major as Next.js moves.

**ALTERNATIVE: Stay on the Pages Router with timed regeneration and webhooks while**

- A working Pages Router site would need a full rewrite to move, because next-sanity's live helpers run on the App Router only.
- Timed regeneration plus a signed webhook is fresh enough for your editors.
- A preview in the real template, without overlays, is all editors need.

## What does next-sanity give a Next.js team?

next-sanity is Sanity's official Next.js package: one dependency that wraps the Sanity client, live content, Visual Editing and an embeddable Sanity Studio for Next.js patterns ([Sanity Docs, Sanity and Next.js](https://www.sanity.io/docs/nextjs/introduction), October 2026). Running `npx sanity@latest init` inside a Next.js project scaffolds the configuration, a configured client and an optional Studio route. The package exports:

- `createClient`, a Sanity client set up for Next.js `fetch` caching.
- `defineLive`, which returns `sanityFetch` and `<SanityLive />` for the Live Content API (application programming interface).
- `VisualEditing` and `defineEnableDraftMode` for click-to-edit overlays in the Presentation tool.
- `NextStudio`, which mounts Sanity Studio as a route in your app.
- `defineQuery` for GROQ (Graph-Relational Object Queries) with TypeGen types, and `parseBody` for webhook signatures.

The version you can install depends on your Next.js major, because each next-sanity major declares a Next.js peer range on npm ([npm registry, next-sanity](https://registry.npmjs.org/next-sanity), October 2026):

**Every next-sanity release numbered 12.0.0 or higher requires Next.js 16**

| next-sanity release | Published | Next.js peer range | React peer range |
| --- | --- | --- | --- |
| 11.4.2 | 26 September 2025 | 15.1 or later, below 16 | 18.3 or 19 |
| 11.6.13, the last 11.x | 14 April 2026 | 15.1 or 16 | 18.3 or 19 |
| 12.0.0 | 16 December 2025 | 16 | 19.2.3 or later |
| 13.4.0, the latest | 23 October 2026 | 16 | 19.2.3 or later |

Sources: [npm, next-sanity package metadata](https://registry.npmjs.org/next-sanity); [Sanity Docs, Query content in Next.js](https://www.sanity.io/docs/nextjs/query-content-nextjs). As of 24 October 2026.

## How do you fetch and cache Sanity content in Next.js?

Sanity recommends `sanityFetch` from `defineLive` for most Next.js apps, because it tags each query and `<SanityLive />` refreshes the tagged content when editors publish ([Sanity Docs, Query content in Next.js](https://www.sanity.io/docs/nextjs/query-content-nextjs), October 2026). The alternatives are a hand-built `sanityFetch` wrapper or `client.fetch` with `next.revalidate` on every call.

Two independent caches decide freshness: the Sanity API (application programming interface) CDN (content delivery network) when `useCdn` is true, and the Next.js data cache ([Caching and revalidation in Next.js](https://www.sanity.io/docs/nextjs/caching-and-revalidation-in-nextjs), October 2026). Three rules avoid common stale-page causes:

- In the manual helper, tags and time-based revalidation are mutually exclusive, so tagged queries stay cached until a webhook busts them ([Caching and revalidation in Next.js](https://www.sanity.io/docs/nextjs/caching-and-revalidation-in-nextjs)).
- Don't mix the two functions named `sanityFetch` in one project.
- Set `useCdn: false` for static builds and webhook revalidation, and `useCdn: true` for server renders on every page view ([Configuring the Sanity client for Next.js](https://www.sanity.io/docs/nextjs/configure-sanity-client-nextjs), October 2026).

On the Pages Router, you fetch in `getStaticProps` with a `revalidate` interval and a `useCdn: false` client ([Query content in Next.js](https://www.sanity.io/docs/nextjs/query-content-nextjs)). Timed ISR (Incremental Static Regeneration) is a request budget. A page on `revalidate: 60` with steady traffic regenerates up to 1,440 times a day. If each regeneration runs one query, that's 43,200 requests in a 30-day month, against 250,000 uncached API requests a month on Free and Growth ([Sanity pricing](https://www.sanity.io/pricing), as of October 2026; Deploi arithmetic from the figures above).

## How should webhooks revalidate a Next.js site when editors publish?

A webhook powered by GROQ (Graph-Relational Object Queries) should call one signed route in your Next.js app, and that route revalidates the paths or tags the changed document affects ([Revalidate Next.js pages with Sanity webhooks](https://www.sanity.io/docs/nextjs/validating-sanity-webhooks-nextjs), October 2026). The webhook's filter decides which edits fire it. GROQ-powered webhooks are capped at 2 on Free and 4 on Growth as of October 2026 ([Sanity pricing](https://www.sanity.io/pricing)), so map many document types to paths in one route instead of one webhook per type.

The Next.js router changes the tooling. `parseBody` from `next-sanity/webhook` only supports App Router route handlers. A Pages Router API (application programming interface) route validates with `isValidSignature` from `@sanity/webhook` and must read the raw body ([Revalidate Next.js pages with Sanity webhooks](https://www.sanity.io/docs/nextjs/validating-sanity-webhooks-nextjs)):

**Pages Router webhook routes turn off Next.js body parsing so the signature can be checked (Sanity Docs)**

```typescript
export const config: PageConfig = {
  api: {
    bodyParser: false,
  },
}
```

`parseBody` also waits 3 seconds so Content Lake can reach eventual consistency before your page refetches; Sanity's Pages Router example copies that wait.

We built this pattern for deploi.ca's Shopify FAQ hub, and its signed route is live. Its filter skips edits that only change a view counter, and its projection sends the old slug, so a slug change also clears the previous URL. The design is in revalidating FAQ pages from a signed webhook.

**How the signed webhook route is built to revalidate a published FAQ answer**

- Sanity Studio -> Content Lake: an editor publishes an FAQ answer
- Content Lake -> GROQ-powered webhook: the filter drops view-counter-only edits
- GROQ-powered webhook -> Next.js API route: a signed payload with the new and old slug
- Next.js API route -> Incremental Static Regeneration (ISR) cache: res.revalidate on the page, its old URL and its parent

## How do previews and Visual Editing work with Next.js?

Previews in Next.js run through Draft Mode, and Sanity's Presentation tool switches it on. Presentation visits your app's enable route with a generated secret, the route validates that secret against the dataset, then turns on Draft Mode so the app fetches drafts ([Sanity Learn, Configuring Presentation](https://www.sanity.io/learn/course/visual-editing-with-next-js/configuring-presentation), October 2026). In Draft Mode, stega encoding maps rendered text back to its document and field, which is how [Visual Editing](https://deploi.ca/sanity/features/visual-editing) opens the right field when an editor clicks the page.

Both of Sanity's setup guides now assume Next.js 16. The App Router guide needs next-sanity v13.1.5 or later ([Visual Editing with Next.js App Router](https://www.sanity.io/docs/visual-editing/visual-editing-with-next-js-app-router), October 2026). The Pages Router guide needs Next.js 16.x, React 19.2.3 or later and Node.js 22.12 or later ([Visual Editing with Next.js Pages Router](https://www.sanity.io/docs/visual-editing/visual-editing-with-next-js-pages-router), October 2026). Drafts need a token with Viewer rights, and only Viewer rights, because anyone in Draft Mode can read it ([Configuring the Sanity client for Next.js](https://www.sanity.io/docs/nextjs/configure-sanity-client-nextjs), October 2026).

deploi.ca's Shopify FAQ hub runs an older Next.js release, so neither guide applies as written. Its preview swaps a one-time key for a cookie, and preview pages are noindex and uncached. Editors see a draft rendered in the real template, but get no click-to-edit overlay. That trade is acceptable for answers written in structured fields; a marketing team building pages visually needs the Presentation tool, and Sanity's current setup guides for it assume Next.js 16.

## What breaks at scale with Sanity and Next.js?

Five failures hit Sanity and Next.js sites, mostly as extra requests or blank pages. Here API (application programming interface) and CDN (content delivery network) mean Sanity's endpoints. Four of these five failures have a cause and fix documented by Sanity; the fifth comes from deploi.ca's production code:

**Five Sanity and Next.js failures, their causes and fixes**

| Symptom | Cause | Fix |
| --- | --- | --- |
| Sanity API requests jump 4x after a Next.js 16 upgrade | SanityLive on next-sanity v12 with the new Link prefetching | Upgrade to next-sanity v13 |
| API requests grow with traffic | useCdn false on a client that renders every page view | Use the API CDN for published content |
| A page renders empty, with no error | A server query without a token against a private dataset | Give the server client a Viewer token |
| Drafts show on the live site, or vanish after an upgrade | The default perspective was raw before API version 2025-02-19 and is published from it | Pin apiVersion and set the perspective on purpose |
| A new page stays 404 after it's published | notFound returned without a revalidate value | Revalidate the not-found branch too |

Rows 4 and 5 are also lessons in deploi.ca's production Next.js code; rows 1 to 4 are documented by Sanity ([request overages](https://www.sanity.io/docs/help/nextjs-16-sanitylive-status), [request spikes](https://www.sanity.io/docs/platform-management/diagnose-api-request-spikes), [live content](https://www.sanity.io/docs/developer-guides/live-content-guide), [perspectives](https://www.sanity.io/docs/content-lake/perspectives)). Sources: [Sanity Docs, Next.js 16 and SanityLive: avoiding request overages](https://www.sanity.io/docs/help/nextjs-16-sanitylive-status); [Sanity Docs, Diagnose an API request spike](https://www.sanity.io/docs/platform-management/diagnose-api-request-spikes); [Sanity Docs, Add live content to your application](https://www.sanity.io/docs/developer-guides/live-content-guide); [Sanity Docs, Perspectives for Content Lake](https://www.sanity.io/docs/content-lake/perspectives). As of 24 October 2026.

The first row is the expensive one. Sanity measured an average 4x increase in request load after the upgrade, and 7 to 10x or more on marketing and docs sites with many segments; next-sanity v13.0.0, shipped 21 May 2026, changes the default ([Next.js 16 and SanityLive](https://www.sanity.io/docs/help/nextjs-16-sanitylive-status), October 2026). The third row is the hardest to spot, because an empty result looks exactly like an unseeded dataset. Sanity's docs confirm that `count(*)` returns `0` and a document query returns `null` ([Add live content to your application](https://www.sanity.io/docs/developer-guides/live-content-guide), October 2026).

Live Content API connections are capped at 1,000 per dataset on Free and Growth ([Sanity pricing](https://www.sanity.io/pricing), October 2026).

## Should you use the App Router or the Pages Router with Sanity?

Use the App Router for a new Sanity build. Sanity's live helpers, `defineLive` and `<SanityLive />`, are App Router only ([Query content in Next.js](https://www.sanity.io/docs/nextjs/query-content-nextjs), October 2026), and Next.js itself recommends migrating to the App Router while it keeps supporting the Pages Router ([Next.js, Pages Router](https://nextjs.org/docs/pages), October 2026). Webhook revalidation, previews through Draft Mode and ISR (Incremental Static Regeneration) work on both.

An existing Pages Router site can stay where it is. deploi.ca's Shopify sections run on an older Next.js release with the Pages Router and next-sanity ^11.4.2. Every 11.x release from 11.4.2 declares Next.js 15.1 or later as its peer, so our install runs outside the supported range ([npm registry, next-sanity](https://registry.npmjs.org/next-sanity), October 2026). The FAQ Hub with AI Chatbot template, which Martin Dejnicki published on Sanity Exchange, uses the Pages Router on Next.js 16.0.7 with next-sanity 11.6, inside the supported range.

> **When not to move a Pages Router site**
>
> - Your pages change through timed ISR and editors don't need click-to-edit.
> - The only driver is live updates for visitors: a signed webhook revalidates the page when an edit is published, without waiting for a timer.
> - You can't take Next.js 16 and React 19.2 in the same project yet.

## Deploi's point of view

**Where we disagree.** Tutorials sell live content as the end of caching worries. It moves the cost: on next-sanity v12 with Next.js 16, Sanity measured a 4x average jump in request load. The other common advice, set useCdn to false for fresh data, is right for builds and webhook revalidation and wrong for server renders on every page view, where it makes your API quota grow with traffic.

**What we've seen.** deploi.ca's Shopify sections run on an older Next.js release with the Pages Router and next-sanity ^11.4.2, below the Next.js range every 11.x release declares. Most pages regenerate on 60 or 300 second timers, and the FAQ hub adds a signed webhook route that refuses unsigned or stale requests. One lesson sits in our client code as a warning: a 404 returned without a revalidate value stays cached, so our not-found branch revalidates every 60 seconds.

**How we scope it.** We start from three facts: the Next.js major, the router, and whether editors need click-to-edit. Next.js 16 on the App Router gets the current next-sanity, defineLive and Visual Editing; Next.js 15.1 on the App Router can run both on next-sanity 11.6.13. Anything older gets ISR, a signed webhook route and a template preview, with the upgrade priced separately.

**What we'd tell you to do first.** Before launch, open the project's Usage tab in Manage and compare API requests with API CDN requests for a week of real traffic. If live API requests grow with page views, a server client has useCdn set to false where it shouldn't.

## When this answer changes

- next-sanity ships a major that changes the Next.js peer range or the SanityLive defaults
- Sanity's setup guides add a Visual Editing path for Next.js 15 or for the Pages Router before Next.js 16, or next-sanity stops shipping 11.x releases for Next.js 15
- Next.js announces an end of support for the Pages Router
- Sanity changes the number of GROQ-powered webhooks on Free or Growth
- Sanity changes the 250,000 API request quota on Free or Growth

## Is Sanity the right CMS for your Next.js build?

See how Sanity compares with the other headless CMSs Next.js teams shortlist, and when another one wins. [Compare CMSs for Next.js](https://deploi.ca/sanity/compare/best-headless-cms-for-nextjs)

## Sources

1. [Sanity Docs, Sanity and Next.js](https://www.sanity.io/docs/nextjs/introduction), checked 24 October 2026
2. [Sanity Docs, Query content in Next.js](https://www.sanity.io/docs/nextjs/query-content-nextjs), checked 24 October 2026
3. [Sanity Docs, Next.js 16 and SanityLive: avoiding request overages](https://www.sanity.io/docs/help/nextjs-16-sanitylive-status), checked 24 October 2026
4. [Sanity Docs, Add live content to your application](https://www.sanity.io/docs/developer-guides/live-content-guide), checked 24 October 2026
5. [Sanity Docs, Caching and revalidation in Next.js](https://www.sanity.io/docs/nextjs/caching-and-revalidation-in-nextjs), checked 24 October 2026
6. [Sanity Docs, Revalidate Next.js pages with Sanity webhooks](https://www.sanity.io/docs/nextjs/validating-sanity-webhooks-nextjs), checked 24 October 2026
7. [Sanity Docs, Visual Editing with Next.js Pages Router](https://www.sanity.io/docs/visual-editing/visual-editing-with-next-js-pages-router), checked 24 October 2026
8. [Sanity Learn, Configuring Presentation](https://www.sanity.io/learn/course/visual-editing-with-next-js/configuring-presentation), checked 24 October 2026
9. [Sanity Docs, Diagnose an API request spike](https://www.sanity.io/docs/platform-management/diagnose-api-request-spikes), checked 24 October 2026
10. [Sanity Docs, Perspectives for Content Lake](https://www.sanity.io/docs/content-lake/perspectives), checked 24 October 2026
11. [npm, next-sanity package metadata](https://registry.npmjs.org/next-sanity), checked 24 October 2026
12. [Next.js, Pages Router](https://nextjs.org/docs/pages), checked 24 October 2026
13. [Sanity, Plans that scale with you](https://www.sanity.io/pricing), checked 24 October 2026
14. [Sanity Docs, Configuring the Sanity client for Next.js](https://www.sanity.io/docs/nextjs/configure-sanity-client-nextjs), checked 24 October 2026
15. [Sanity Docs, Visual Editing with Next.js App Router](https://www.sanity.io/docs/visual-editing/visual-editing-with-next-js-app-router), checked 24 October 2026