How I set up Sanity Studio with live preview in Next.js App Router using Presentation

Sanity's Presentation plugin is the cleanest live-preview setup I've shipped for editorial teams — editors click any text in the embedded iframe and land directly on the relevant field in Studio. Setting it up against Next.js App Router takes about two hours the first time; this post captures every non-obvious step so yours takes twenty minutes.

What Sanity Presentation actually does

Presentation is a Sanity Studio plugin that embeds your front-end URL in an iframe alongside the Studio editor. It uses @sanity/visual-editing on the Next.js side to attach data-sanity-* attributes to rendered elements. When an editor clicks a heading in the preview, Studio jumps to that document field. Under the hood it's built on @sanity/channels — a lightweight postMessage bus between the iframe and the parent Studio frame.

This is different from the older watch-mode preview pattern where you had a separate /api/draft route and a full page reload. With Presentation, GROQ queries re-run live as the editor types, with no reload.

Prerequisites

You need:

next ≥ 14.2 (App Router)
sanity ≥ 3.30 (Presentation is stable from 3.28 but 3.30 fixes a critical iframe CSP bug)
@sanity/visual-editing ≥ 2.1
@sanity/preview-kit ≥ 5.0 (for live GROQ on the Next.js side)

Install once:

npm i @sanity/visual-editing @sanity/preview-kit sanity@latest

Step 1 — Configure Presentation in sanity.config.ts

// sanity.config.ts
import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import { presentationTool } from 'sanity/presentation'

export default defineConfig({
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  plugins: [
    structureTool(),
    presentationTool({
      // The origin of your Next.js dev or preview URL
      previewUrl: {
        origin:
          process.env.SANITY_STUDIO_PREVIEW_URL ?? 'http://localhost:3000',
        // Presentation will append ?sanity-preview-secret=<token> automatically
        // when the user enters draft mode from Studio.
        draftMode: {
          enable: '/api/draft-mode/enable',
        },
      },
    }),
  ],
})

The draftMode.enable path must be a route handler in your Next.js app that sets the Next.js draft mode cookie. Keep the secret out of the config — Presentation reads it from the URL param and validates server-side.

Step 2 — The draft mode enable route handler

// app/api/draft-mode/enable/route.ts
import { validatePreviewUrl } from '@sanity/preview-url-secret'
import { client } from '@/sanity/client' // your configured sanity client
import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'
import { type NextRequest } from 'next/server'

export async function GET(req: NextRequest) {
  const { isValid, redirectTo = '/' } = await validatePreviewUrl(
    // Pass a client with a read token — never the write token
    client.withConfig({ token: process.env.SANITY_API_READ_TOKEN }),
    req.url,
  )

  if (!isValid) {
    return new Response('Invalid secret', { status: 401 })
  }

  // next/headers draftMode() is synchronous in Next.js 15+
  ;(await draftMode()).enable()
  redirect(redirectTo)
}

A few things that bit me on real projects:

validatePreviewUrl makes a GROQ query to your Sanity project to confirm the secret exists as a document of type sanity.previewUrlSecret. Run npx sanity@latest manage → API → Preview URL Secrets to generate one, or use the CLI: npx sanity preview-url-secret create.
The read token needs viewer role minimum. Do not use the deploy token here.
In Next.js 15, draftMode() returns a Promise — add the await or you get a runtime error.

Step 3 — Add visual-editing overlays to your layout

The VisualEditing component from @sanity/visual-editing/next attaches the attribute listeners and opens the Studio postMessage channel. Render it only when draft mode is active:

// app/layout.tsx
import { draftMode } from 'next/headers'
import { VisualEditing } from '@sanity/visual-editing/next'

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const { isEnabled } = await draftMode()

  return (
    <html lang="en">
      <body>
        {children}
        {isEnabled && <VisualEditing />}
      </body>
    </html>
  )
}

This is all you need for click-to-field navigation. Visual editing will auto-detect data-sanity-* attributes that Sanity's studioUrl helper injects when you use @sanity/preview-kit's live store.

Step 4 — Swap to a live GROQ store in draft mode

For real-time field updates as the editor types, replace your static sanity.fetch() calls with useLiveQuery from @sanity/preview-kit. This only needs to happen inside a client component boundary — all your RSC page shells stay server components.

The pattern I use: a LiveQueryProvider in a server component passes the initial data down, and a thin client component hydrates it live.

// app/(preview)/PreviewProvider.tsx  — client boundary
'use client'
import { LiveQueryProvider } from '@sanity/preview-kit'
import { client } from '@/sanity/client'

export function PreviewProvider({
  token,
  children,
}: {
  token: string
  children: React.ReactNode
}) {
  return (
    <LiveQueryProvider client={client} token={token} logger={console}>
      {children}
    </LiveQueryProvider>
  )
}

Wrap this around the page tree only when draftMode().isEnabled. Pass process.env.SANITY_API_READ_TOKEN from the server — it never reaches the client bundle because you're passing it as a prop from a Server Component into this Client Component, and React serialises it only for the initial render. The token is in the HTML source for draft-mode sessions, which is acceptable because those sessions are gated behind the secret.

Disabling draft mode

Add a /api/draft-mode/disable route that calls draftMode().disable() and redirects back. Wire a "Exit preview" button using a Server Action or a simple link to that route. Presentation also adds its own toolbar with an exit button, but having an independent escape hatch is worth the two extra lines.

Staging vs production

Set SANITY_STUDIO_PREVIEW_URL to your Vercel preview URL in the Studio's environment config. Because Vercel preview URLs change per branch, I set this in sanity.config.ts to fall back to window.location.origin when the env is absent — that way the deployed Studio on studio.yourproject.com previews against whatever domain the editor last manually loaded.

One gotcha: if your Next.js app sets a restrictive frame-ancestors CSP, the Presentation iframe will silently blank. Add frame-ancestors 'self' https://your-studio-domain.sanity.studio to the Content-Security-Policy header in next.config.ts. This is the most common reason Presentation appears broken on first deploy.

推荐订阅源

DEV Community