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 (which calls cacheTag/cacheLife internally), 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 the next-cache-components skill — it covers 'use cache', cacheLife, cacheTag, and the cookies/headers/params rule. 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).

Prerequisites

• Next.js 16.2+ 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).
• AGENTS.md exists, or 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 sanityFetchStaticParams.
• Search for sanityFetch calls inside generateMetadata / sitemap.ts / opengraph-image.tsx / etc. → swap for sanityFetchMetadata.
• Search for sanityFetch calls directly inside a 'use server' function → split into a separate 'use cache' helper.
• 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 minimal defineLive call:

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

Full file contents (including client.ts, getDynamicFetchOptions, sanityFetchMetadata, sanityFetchStaticParams) 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>
  )
}