How do Sanity and Next.js work together?

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, 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, 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, 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, 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).
• 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, October 2026).

On the Pages Router, you fetch in getStaticProps with a revalidate interval and a useCdn: false client (Query content in Next.js). 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, 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, 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), 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):

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 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, October 2026). In Draft Mode, stega encoding maps rendered text back to its document and field, which is how 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, 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, 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, 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:

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, 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, October 2026).

Live Content API connections are capped at 1,000 per dataset on Free and Growth (Sanity 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, October 2026), and Next.js itself recommends migrating to the App Router while it keeps supporting the Pages Router (Next.js, Pages Router, 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, 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.