Index of every page on this site: llms.txt
All skills
robotostudio avatar

/sanity-live-cache-components

@c0b29e4
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/robotostudio/turbo-start-sanity/sanity-live-cache-components

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencethree-layer-pattern.md

≈1.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Three-layer component pattern

The core architecture for every route that can be fully statically prerendered and cached.

Contents

Structure

Page/Layout (Layer 1)
  ├── NOT draft mode → <CachedX perspective="published" stega={false} />  (no Suspense)
  └── draft mode → <Suspense fallback={...}>
                      <DynamicX params={params} />  (Layer 2)
                        └── <CachedX params={await params} perspective={p} stega={s} />  (Layer 3)

generateStaticParams for dynamic routes

The examples below use /[slug]/page.tsx, which needs:

// src/app/[slug]/page.tsx
import {sanityFetchStaticParams} from '@/sanity/lib/live'
import {defineQuery} from 'next-sanity'

export async function generateStaticParams() {
  const pageSlugsQuery = defineQuery(
    `*[_type == "page" && defined(slug.current)]{"slug": slug.current}`,
  )
  const {data} = await sanityFetchStaticParams({query: pageSlugsQuery})
  return data
}

For /layout.tsx or /page.tsx (no params), skip the params handling.

Layer 1: Page component

Calls draftMode() and branches:

// src/app/[slug]/page.tsx (continued)
import {draftMode} from 'next/headers'
import {Suspense} from 'react'

export default async function Page({params}: PageProps<'/[slug]'>) {
  const {isEnabled: isDraftMode} = await draftMode()
  if (isDraftMode) {
    return (
      <Suspense fallback={<PageFallback />}>
        <DynamicPage
          // do not await `params` here, it needs to be awaited in `<DynamicPage>` so the Suspense boundary works
          params={params}
        />
      </Suspense>
    )
  }
  const {slug} = await params
  return <CachedPage slug={slug} perspective="published" stega={false} />
}

Notes:

  • Page does not have a 'use cache' directive. draftMode() is allowed inside 'use cache', but Page also awaits params (and may call getDynamicFetchOptions(), which reads cookies()), and those dynamic APIs are not allowed inside 'use cache'. It's enough for <CachedPage> (Layer 3) to carry 'use cache' for Page to be prerendered as part of the static shell.

  • Requires generateStaticParams if params is used as input to sanityFetch.

  • Not in draft mode → no <Suspense> boundary, maximizes the static shell.

  • In draft mode → <DynamicPage /> inside <Suspense> will suspend twice:

    1. when <DynamicPage> awaits getDynamicFetchOptions()
    2. when <CachedPage /> awaits sanityFetch with the resolved perspective/stega

    A good fallback skeleton that doesn't cause layout shift is highly recommended.

Layer 2: Dynamic component

Resolves params, cookies(), and headers() outside the cache boundary and passes plain props in:

// src/app/[slug]/page.tsx (continued)
import {getDynamicFetchOptions} from '@/sanity/lib/live'

async function DynamicPage({params}: Pick<PageProps<'/[slug]'>, 'params'>) {
  const [{slug}, {perspective, stega}] = await Promise.all([params, getDynamicFetchOptions()])

  return <CachedPage slug={slug} perspective={perspective} stega={stega} />
}

draftMode() is the only dynamic API allowed inside 'use cache', but in this pattern it isn't needed in Layer 3 because perspective and stega already encode the draft state.

Layer 3: Cached component

Has 'use cache' and only receives plain, serializable props:

// src/app/[slug]/page.tsx (continued)
import {sanityFetch, type DynamicFetchOptions} from '@/sanity/lib/live'
import {defineQuery} from 'next-sanity'

async function CachedPage({
  slug,
  perspective,
  stega,
}: Awaited<PageProps<'/[slug]'>['params']> & DynamicFetchOptions) {
  'use cache'
  const pageQuery = defineQuery(`*[_type == "page" && slug.current == $slug][0]`)
  const {data} = await sanityFetch({
    query: pageQuery,
    params: {slug},
    perspective,
    stega,
  })
  return <article>{/* use `data` to render stuff */}</article>
}

searchParams and other dynamic APIs

If searchParams or other dynamic APIs are inputs to sanityFetch (or params is used without generateStaticParams or a loading.tsx), always render the <Suspense> tree and stop branching on draftMode. See the streaming guide for picking between loading.tsx and <Suspense>.

// src/app/[slug]/page.tsx (continued)
import {Suspense} from 'react'

// Do not export an async function here, to avoid accidentally blocking render while awaiting a dynamic API
export default function Page({params}: PageProps<'/[slug]'>) {
  return (
    <Suspense
      // not optional — no draftMode branch means a missing skeleton causes massive layout shift
      fallback={<PageFallback />}
    >
      <DynamicPage
        // do not await `params` here, it needs to be awaited in `<DynamicPage>` so the Suspense boundary works
        params={params}
      />
    </Suspense>
  )
}

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    The skill provides architectural patterns and boilerplate for integrating Sanity CMS with Next.js Cache Components. It follows industry best practices for handling API tokens and implementing secure, high-performance data fetching strategies.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: MEDIUM · 1 issue

Signed by skilld at c0b29e4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 months ago

README badge

README badge for robotostudio/turbo-start-sanity/sanity-live-cache-components