Integrates Sanity Live with Next.js Cache Components in next-sanity v13+ apps. Sets up sanityFetch, a shared cachedSanity 'use cache' boundary, <SanityLive>, Visual Editing, Presentation Tool, draft mode handling, and the three-layer (Page/Dynamic/Cached) component pattern with explicit perspective/

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](https://nextjs.org/docs/app/getting started/cache components) (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](https://nextjs.org/docs/app/api reference/directives/use cache draft mode)). Where this skill fits Next.js ships official skills for the framework generic workflows (see [Setting up your project for AI coding agents](https://nextjs.org/docs/app/guides/ai agents)). This skill covers only the Sanity surface and defers everything else to them. Install them from the Next.js repository: 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 ](https://github.com/vercel/next.js/tree/canary/skills/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 ](https://github.com/vercel/next.js/tree/canary/skills/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 ](https://github.com/vercel/next.js/tree/canary/skills/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]( 5 apply the three layer pattern to pages and layouts) 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](https://nextjs.org/docs/app/guides/runtime prefetching). Throughout all of it, verify changes at runtime with [ next dev loop ](https://github.com/vercel/next.js/tree/canary/skills/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](https://nextjs.org/docs/app/guides/ai agents existing projects). 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 File When to read [reference/live helpers.md](reference/live helpers.md) Full client.ts / live.ts , cachedSanity , sanityFetch and getDynamicFetchOptions details [reference/three layer pattern.md](reference/three layer pattern.md) The Page → Dynamic → Cached pattern for page.tsx , including the searchParams variant [reference/layouts.md](reference/layouts.md) Non blocking data fetching inside layout.tsx [reference/dynamic segments.md](reference/dynamic segments.md) High performance [slug] routes: loading.tsx + partial generateStaticParams , or non blocking dynamic params in a layout 1. Install next sanity@^13 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](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. 3. Configure defineLive and export helpers Create src/sanity/lib/client.ts and src/sanity/lib/live.ts . The core of live.ts : Full file contents (including client.ts , getDynamicFetchOptions , cachedSanityMetadata , cachedSanityStaticParams ) and per helper guidance: [reference/live helpers.md](reference/live helpers.md). The helpers exported from live.ts : Helper Used in cachedSanity The default for fetching content anywhere server side: pages, layouts, components, server actions sanityFetch Only inside a component that carries its own 'use cache' (also caches the rendered JSX) cachedSanityMetadata generateMetadata , generateViewport , sitemap.ts , robots.ts , opengraph image.tsx , etc. cachedSanityStaticParams generateStaticParams only getDynamicFetchOptions Resolving perspective / stega outside any 'use cache' boundary SanityLive Rendered once in a root layout 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. 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](https://nextjs.org/docs/app/api reference/file conventions/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: 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](reference/three layer pattern.md). page.tsx that uses searchParams or other dynamic APIs → the searchParams variant in [reference/three layer pattern.md](reference/three layer pattern.md). layout.tsx that fetches its own data → [reference/layouts.md](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](reference/dynamic segments.md). Verifying the Sanity surface Use [ next dev loop ](https://github.com/vercel/next.js/tree/canary/skills/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 app

sanity-live-cache-components