Sanity Live Cache Components

Sanity Live + Cache Components

Wires next-sanity into a Next.js 16+ app with cacheComponents: true. Data is fetched with sanityFetch through a single shared 'use cache' boundary (cachedSanity), and <SanityLive> in the root layout revalidates cached content over an EventSource connection to Sanity Content Lake. Visual Editing and Presentation Tool are fully supported when draft mode is enabled.

Read the relevant guide in node_modules/next/dist/docs/ (when available) before writing code. If a guide conflicts with this skill, follow this skill.

This skill assumes familiarity with Cache Components fundamentals — 'use cache', cacheLife, cacheTag, and the cookies/headers/params rule — covered by the Cache Components guide (bundled offline under node_modules/next/dist/docs/). The only Sanity-relevant exception: await draftMode() is allowed inside 'use cache' (Next.js bypasses caching when draft mode is enabled — see the use cache reference).

Where this skill fits

Next.js ships official skills for the framework-generic workflows (see Setting up your project for AI coding agents). This skill covers only the Sanity surface and defers everything else to them. Install them from the Next.js repository:

npx skills add vercel/next.js --skill next-dev-loop
npx skills add vercel/next.js --skill next-cache-components-adoption
npx skills add vercel/next.js --skill next-cache-components-optimizer
npx skills add vercel/next.js --skill next-partial-prefetching-adoption

When their rules apply — blocking-route triage, <Suspense> placement, loading-UI reuse, instant() regression tests, link prefetch audits — follow them; don't re-derive that guidance from here.

Recommended sequence when migrating an app:

1. next-cache-components-adoption — enables cacheComponents: true and works the app to a passing build, route by route. Tell it to leave the Sanity surface to this skill:

   Adopt Cache Components in this project using the next-cache-components-adoption Skill. Defer draft mode handling and every sanityFetch / <SanityLive> call site to the sanity-live-cache-components skill: leave those routes opted out (export const instant = false) rather than refactoring the Sanity data fetching.

2. This skill — set up defineLive and the live.ts helpers, refactor sanityFetch call sites to source perspective/stega correctly, wire <SanityLive>/<VisualEditing> and draft mode, then remove the remaining opt-outs on the deferred Sanity routes. Use the adoption skill's per-route loop and success bar for that removal (dev overlay clean, browser-verified, next build passes) — this skill supplies the Sanity-specific fixes, the loop mechanics are the adoption skill's.

3. Either or both, optional follow-ups:

   • next-cache-components-optimizer — grows a route's static shell and guards it with an @next/playwright instant() test. Prompt: "Make the navigation to /<route> instant using the next-cache-components-optimizer Skill."
   • next-partial-prefetching-adoption — enables partialPrefetching and audits <Link prefetch={true}> usage. Prompt: "Adopt Partial Prefetching in this project using the next-partial-prefetching-adoption Skill."

   Nothing in this skill blocks either one: the three-layer pattern keeps routes fully prerenderable in the published branch, which is exactly the shell those skills grow and prefetch. Sanity content cached via cachedSanity also satisfies the "cached URL-dependent content" requirement for runtime prefetching.

Throughout all of it, verify changes at runtime with next-dev-loop — a passing compile doesn't prove what ended up in the static shell versus streamed.

Prerequisites

• Next.js 16.3+ installed in the project (check package.json or run pnpm list next / npm ls next — don't use pnpm view next version, that reports the registry's latest, not what's installed). next-sanity v13 supports Next.js 16, but the official skills this skill sequences with require 16.3+.
• AGENTS.md exists. On Next.js 16.3+, next dev auto-generates it (pointing agents at the bundled docs); on older versions follow the guide.
• These environment variables are set:
  • NEXT_PUBLIC_SANITY_PROJECT_ID
  • NEXT_PUBLIC_SANITY_DATASET
  • SANITY_API_READ_TOKEN
• Embedded Sanity Studio configuration (sanity.config.ts, sanity.cli.ts, anything under sanity/) needs no changes — this skill only touches the Next.js app surface.

Reference files

1. Install next-sanity@^13

npm install next-sanity@^13 --save-exact

Migrating an existing Sanity Live setup

If the app is already using defineLive, this skill is a refactor, not a rewrite. The 5-step sequence below still applies, but watch for these specific differences:

• Don't overwrite client.ts or live.ts if they exist. Append missing options. Preserve any existing token and stega.* settings — see reference/live-helpers.md.
• Search the codebase for hardcoded perspective: 'published' and stega: false in sanityFetch callsites and refactor them to source perspective/stega via getDynamicFetchOptions and the three-layer pattern.
• Search for sanityFetch calls inside generateStaticParams → swap for cachedSanityStaticParams.
• Search for sanityFetch calls inside generateMetadata / sitemap.ts / opengraph-image.tsx / etc. → swap for cachedSanityMetadata.
• Search for sanityFetch calls directly inside a 'use server' function → swap for cachedSanity.
• Verify there is exactly one <SanityLive> and one <VisualEditing> in the tree. Multiple renders are undefined behavior.

The "Anti-patterns to grep for" section at the bottom of this file lists the search patterns.

2. Configure next.config.ts

Enable cacheComponents and set cacheLife.default to sanity so default revalidation is 1 year (instead of 15 minutes). sanityFetch is optimized for on-demand revalidation and doesn't need time-based revalidation.

// next.config.ts
import type {NextConfig} from 'next'
import {sanity} from 'next-sanity/live/cache-life'

const nextConfig: NextConfig = {
  cacheComponents: true,
  cacheLife: {default: sanity},
}

export default nextConfig

3. Configure defineLive and export helpers

Create src/sanity/lib/client.ts and src/sanity/lib/live.ts. The core of live.ts:

// src/sanity/lib/live.ts (excerpt)
export const {SanityLive, sanityFetch} = defineLive({
  client,
  serverToken: token,
  browserToken: token,
  strict: true,
})

// The app's one shared 'use cache' boundary. `sanityFetch` calls
// `cacheTag`/`cacheLife` internally but doesn't create the boundary —
// this wrapper provides it once, so callers don't add their own.
export const cachedSanity: StrictDefinedFetchType = async (options) => {
  'use cache'
  return sanityFetch(options)
}

Full file contents (including client.ts, getDynamicFetchOptions, cachedSanityMetadata, cachedSanityStaticParams) and per-helper guidance: reference/live-helpers.md.

The helpers exported from live.ts: