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:

4. Render <SanityLive> in a root layout

<SanityLive> and <VisualEditing> both belong in a layout.tsx, never a page.tsx. Both must be rendered at most once across the whole tree — duplicate renders are undefined behavior.

• includeDrafts is required when defineLive is configured with strict: true (the recommended setup). TypeScript will surface the error if it's missing; pass includeDrafts={isDraftMode} so live revalidation includes drafts only in draft mode.
• Preserve any existing optional callback props on <SanityLive> when migrating: onError, onWelcome, onReconnect. They are commonly wired to a toast/notification helper and silently dropping them regresses UX.

// src/app/layout.tsx
import {SanityLive} from '@/sanity/lib/live'
import {VisualEditing} from 'next-sanity/visual-editing'
import {draftMode} from 'next/headers'
 
export default async function RootLayout({children}: LayoutProps<'/'>) {
  const {isEnabled: isDraftMode} = await draftMode()
  return (
    <html lang="en">
      <body>
        {children}
        <SanityLive includeDrafts={isDraftMode} />
        {isDraftMode && <VisualEditing />}
      </body>
    </html>
  )
}

With an embedded Sanity Studio

If a route mounts NextStudio from next-sanity/studio (e.g. app/studio/[[...index]]/page.tsx), <SanityLive> must live in a layout the embedded studio doesn't share. Use route groups: put <SanityLive> in src/app/(website)/layout.tsx and keep the rest of the app under src/app/(website).

5. Apply the three-layer pattern to pages and layouts

Every route that should be statically prerendered uses the same shape:

Page/Layout (Layer 1: draftMode branch)
  ├── NOT draft mode → <CachedX perspective="published" stega={false} />  (no Suspense)
  └── draft mode → <Suspense fallback={...}>
                      <DynamicX params={params} />  (Layer 2: awaits dynamic APIs)
                        └── <CachedX perspective={p} stega={s} />  (Layer 3: fetches via cachedSanity)

Critical rules:

• The cache boundary lives in live.ts (cachedSanity), so route files usually carry no 'use cache' directive at all. In particular the top-level Page / Layout must not have 'use cache' — it awaits params, searchParams, or cookies() (via getDynamicFetchOptions), and those dynamic APIs are forbidden inside 'use cache'. Adding 'use cache' to the top-level function is the most common failure mode — TypeScript and the runtime will both complain.
• Layer 3 awaiting cachedSanity is enough for the whole route to prerender into the static shell — no <Suspense> needed in the published branch. perspective and stega are part of the wrapper's cache key automatically, so published and draft content never share a cache entry.
• Only Layer 2 (rendered inside <Suspense>, draft mode only) touches dynamic APIs.

Pick the right reference for the file you're editing:

• page.tsx with static or generateStaticParams-backed params → reference/three-layer-pattern.md.
• page.tsx that uses searchParams or other dynamic APIs → the searchParams variant in reference/three-layer-pattern.md.
• layout.tsx that fetches its own data → reference/layouts.md.
• Dynamic [slug] route that needs the loading.tsx + partial generateStaticParams optimization, or a layout that needs non-blocking params → reference/dynamic-segments.md.

Verifying the Sanity surface

Use next-dev-loop after each refactor; the loop mechanics and success bar live in the official skills. The Sanity-specific things to confirm:

• Published branch: the route prerenders fully (◐ or ○ in the build's route table) and content renders without a <Suspense> fallback flash.
• Draft mode: enabling it streams draft content, <VisualEditing> overlays appear, and switching perspectives in Presentation Tool changes the rendered content.
• Live updates: editing published content in the Studio revalidates the route (via <SanityLive>) without a rebuild.

Anti-patterns to grep for

When auditing an app, search for these and refactor:

• perspective: 'published' and stega: false hardcoded together in a sanityFetch / cachedSanity call inside a shared component → use the three-layer pattern, source perspective/stega via getDynamicFetchOptions. (Layer 1's non-draft branch passing literal perspective="published" stega={false} props is the pattern, not a violation.)
• sanityFetch( directly inside a function whose body begins with 'use server' → swap for cachedSanity (resolve perspective/stega via getDynamicFetchOptions first).
• sanityFetch( inside generateStaticParams → swap for cachedSanityStaticParams.
• sanityFetch( inside generateMetadata / generateViewport / sitemap.ts / robots.ts / opengraph-image.tsx etc. → swap for cachedSanityMetadata and resolve perspective via getDynamicFetchOptions.
• sanityFetch( in a component without its own 'use cache' directive → swap for cachedSanity (or add the directive if caching the rendered JSX is intended).
• await draftMode() immediately followed by await getDynamicFetchOptions() at the top of a page.tsx or layout.tsx without a sibling loading.tsx → move those dynamic-API calls into a child component wrapped in <Suspense> so the static shell can prerender.
• More than one <SanityLive> or <VisualEditing> rendered in the tree → consolidate to a single render in the right layout.