npx skills add ...
npx skills add sanity-io/next-sanity --skill sanity-live-cache-components
npx skills add sanity-io/next-sanity --skill sanity-live-cache-components
Integrates Sanity Live with Next.js Cache Components in next-sanity v13+ apps. Sets up sanityFetch, <SanityLive>, Visual Editing, Presentation Tool, draft mode handling, and the three-layer (Page/Dynamic/Cached) component pattern with explicit perspective/stega prop-drilling. Use when configuring or migrating a Next.js app to cacheComponents with Sanity, when adding sanityFetch, when wiring <SanityLive>/<VisualEditing>, or when refactoring components that hardcode perspective/stega.
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).
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.NEXT_PUBLIC_SANITY_PROJECT_IDNEXT_PUBLIC_SANITY_DATASETSANITY_API_READ_TOKENsanity.config.ts, sanity.cli.ts, anything under sanity/) needs no changes — this skill only touches the Next.js app surface.| File | When to read |
|---|---|
| reference/live-helpers.md | Full client.ts / live.ts, sanityFetch* and getDynamicFetchOptions details |
| reference/three-layer-pattern.md | The Page → Dynamic → Cached pattern for page.tsx, including the searchParams variant |
| reference/layouts.md | Non-blocking data fetching inside layout.tsx with a shared 'use cache' helper |
| reference/dynamic-segments.md | High-performance [slug] routes: loading.tsx + partial generateStaticParams, or non-blocking dynamic params in a layout |
next-sanity@^13If 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:
client.ts or live.ts if they exist. Append missing options. Preserve any existing token and stega.* settings — see reference/live-helpers.md.perspective: 'published' and stega: false in sanityFetch callsites and refactor them to source perspective/stega via getDynamicFetchOptions and the three-layer pattern.sanityFetch calls inside generateStaticParams → swap for sanityFetchStaticParams.sanityFetch calls inside generateMetadata / sitemap.ts / opengraph-image.tsx / etc. → swap for sanityFetchMetadata.sanityFetch calls directly inside a 'use server' function → split into a separate 'use cache' helper.<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.
next.config.tsEnable 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.
defineLive and export helpersCreate src/sanity/lib/client.ts and src/sanity/lib/live.ts. The minimal defineLive call:
Full file contents (including client.ts, getDynamicFetchOptions, sanityFetchMetadata, sanityFetchStaticParams) and per-helper guidance: reference/live-helpers.md.
The helpers exported from live.ts:
| Helper | Used in |
|---|---|
sanityFetch | 'use cache' components rendered from page.tsx / layout.tsx |
sanityFetchMetadata | generateMetadata, generateViewport, sitemap.ts, robots.ts, opengraph-image.tsx, etc. |
sanityFetchStaticParams | generateStaticParams only |
getDynamicFetchOptions | Resolving perspective/stega outside any 'use cache' boundary |
SanityLive | Rendered once in a root layout |
<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.<SanityLive> when migrating: onError, onWelcome, onReconnect. They are commonly wired to a toast/notification helper and silently dropping them regresses UX.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).
Every route that should be statically prerendered uses the same shape:
Critical rule: Only Layer 3 carries 'use cache'. 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'. Layer 3 carrying 'use cache' is enough for the whole route to prerender into the static shell. Adding 'use cache' to the top-level function is the most common failure mode — TypeScript and the runtime will both complain.
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.[slug] route that needs the loading.tsx + partial generateStaticParams optimization, or a layout that needs non-blocking params → reference/dynamic-segments.md.When auditing an app, search for these and refactor:
perspective: 'published' and stega: false hardcoded together in a sanityFetch call → use the three-layer pattern, source perspective/stega via getDynamicFetchOptions.sanityFetch( directly inside a function whose body begins with 'use server' → split into a separate 'use cache' helper.sanityFetch( inside generateStaticParams → swap for sanityFetchStaticParams.sanityFetch( inside generateMetadata / generateViewport / sitemap.ts / robots.ts / opengraph-image.tsx etc. → swap for sanityFetchMetadata and resolve perspective via getDynamicFetchOptions.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.<SanityLive> or <VisualEditing> rendered in the tree → consolidate to a single render in the right layout.// src/sanity/lib/live.ts (excerpt)
export const {SanityLive, sanityFetch} = defineLive({
client,
serverToken: token,
browserToken: token,
strict: true,
})// 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>
)
}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: 'use cache')