How do I connect Sanity to a Next.js app with draft mode and live preview/visual editing?

Most teams want their Next.js app to behave like a real content console: editors hit save in Sanity Studio, and the front‑end updates instantly—drafts, live preview, and visual editing included. You get there by wiring your Next.js routes to Sanity’s Content Lake, then layering in draft mode and the Visual Editing overlay.

Quick Answer: Connect Sanity to a Next.js app by installing the Sanity client, wiring GROQ queries into your routes, then enabling Next.js Draft Mode together with @sanity/visual-editing for live preview and visual editing that read unpublished drafts directly from the Content Lake.

Frequently Asked Questions

How do I connect a Sanity project to my Next.js app in the first place?

Short Answer: Install the Sanity client in your Next.js app, configure it with your project ID and dataset, then query content with GROQ (or Sanity’s client APIs) in your route handlers or components.

Expanded Explanation:
Sanity stores your content as JSON documents in the Content Lake and exposes it over a query API. Next.js just needs a client that knows which Sanity project and dataset to talk to. Once configured, you can query content in app/ route handlers, getStaticProps/getServerSideProps, server components, or API routes—whatever matches your routing model.

The key is to keep configuration in a single place (for example, sanity.config.ts and sanity.client.ts) and generate types from your schemas so your Next.js code can rely on typed content structures. From there, you can add draft mode and visual editing on top of a single “query layer” that your app uses everywhere.

Key Takeaways:

• Use a shared Sanity client configured with your projectId, dataset, and API version.
• Centralize GROQ queries and types so your app and preview paths stay in sync.

---

How do I set up draft mode and live preview between Sanity Studio and Next.js?

Short Answer: Use Next.js Draft Mode together with a “preview client” that includes drafts, then render preview components when draft mode is enabled.

Expanded Explanation:
Draft mode in Next.js is essentially a flag stored in a cookie that tells your route to render using draft‑aware data. On the Sanity side, drafts are just additional documents in the dataset whose IDs start with drafts.. The Sanity JavaScript client can include or exclude them based on the perspective or useCdn/token configuration.

The workflow is:

• Provide a preview URL in Sanity Studio that points to a Next.js route (for example, /api/draft).
• That route calls draftMode().enable() (in the App Router) or res.setDraftMode({ enable: true }) (in Pages Router), then redirects to the actual page path.
• The page checks whether draft mode is enabled; if so, it uses a “preview” client that reads drafts and, optionally, subscribes to live changes via @sanity/preview-kit.

Steps:

1. Install dependencies in your Next.js app:

   npm install next-sanity @sanity/preview-kit
   

2. Create a preview client that includes drafts, e.g.:

   // sanity.client.ts
   import { createClient } from 'next-sanity'
   
   const config = {
     projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
     dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
     apiVersion: '2025-01-01',
     useCdn: false, // for draft/preview
     token: process.env.SANITY_API_READ_TOKEN,
   }
   
   export const sanityClient = createClient(config)
   

3. Wire a draft mode entry route (for example, /api/draft) that enables draft mode and redirects to the page being previewed.

---

What’s the difference between draft mode, live preview, and visual editing in this setup?

Short Answer: Draft mode lets your app read unpublished content, live preview keeps the page in sync with content changes, and visual editing overlays Studio‑aware edit links directly on your Next.js UI.

Expanded Explanation:
These three features build on each other:

• Draft mode: Controls which “perspective” of Sanity content you use—published only, or published + drafts. It’s cookie‑based in Next.js and typically enabled through a dedicated route that Studio calls.
• Live preview: Subscribes to Sanity content changes so the page updates without refresh when editors change content in Studio. This usually relies on @sanity/preview-kit and web‑socket based updates.
• Visual editing: Adds an overlay (via @sanity/visual-editing) that maps DOM elements back to Sanity documents and fields, so editors can click your real UI and go straight to the right place in Studio—or see live “editing frames” inline.

Comparison Snapshot:

• Option A: Draft mode only: You see drafts when you reload, but no auto‑updates and no overlay.
• Option B: Draft mode + live preview + visual editing: You see drafts, changes stream into the UI, and editors can click the UI to edit content in context.
• Best for: Teams who want Studio to act like a control panel for the production UI—especially when many locales, brands, or product lines must stay in sync.

---

How do I actually implement visual editing for Sanity in a Next.js app?

Short Answer: Install @sanity/visual-editing, wrap your app with its provider, and annotate your components so the overlay can map DOM elements back to the right Sanity documents and fields.

Expanded Explanation:
Visual editing uses Sanity’s “content-as-data” model and references to generate stable, schema‑aware links from your rendered UI back to the underlying JSON documents. In Next.js, you add an overlay component that runs only when draft mode / preview is active. Your Studio provides the preview URL and, optionally, agent‑driven enrichment or transformations via agent actions.

You can combine visual editing with live preview by using @sanity/preview-kit’s useLiveQuery hook or similar utilities so that content changes in the Content Lake are reflected directly in your React tree, and the overlay stays aligned with the current document state.

What You Need:

• @sanity/visual-editing and @sanity/preview-kit installed in your app.
• Stable Sanity document IDs and references exposed in your components so they can be annotated for visual editing.

---

How does this setup support a long‑term content strategy, not just a demo preview?

Short Answer: Modeling content as structured JSON in Sanity and wiring it to Next.js with draft mode, live preview, and visual editing gives you a governed knowledge layer that can power web, mobile, and agent experiences from the same source.

Expanded Explanation:
When you treat your content as reusable data instead of “pages,” your Next.js app becomes just one consumer of a shared Content Lake. Schemas live in code (in your Studio config), so changes go through the same review and deployment process as the rest of your stack. Draft mode and visual editing become operational tools: editors can stage changes, validate them in the UI they care about, and publish once—knowing those changes will propagate to any channel wired into the same Sanity dataset.

From there, you can layer on Sanity Functions, Agent Actions, and Content Agents to build schema‑aware automation: trigger a storefront rebuild when a product goes live, run copy audits on drafts before publish, or sync localized copies across multiple brands. Next.js remains your presentation layer, but Sanity becomes the system of record that keeps every downstream experience in sync.

Why It Matters:

• Operational consistency: One structured content layer powering many Next.js routes, apps, and internal tools keeps teams from re‑implementing custom APIs and fragile glue code.
• Editor autonomy: Draft mode, live preview, and visual editing let non‑developers own content updates with confidence, reducing the need for engineering to gate every change.

---

Quick Recap

Connecting Sanity to a Next.js app starts with a single configured client and shared GROQ queries. From there, you enable draft mode to read unpublished content, add live preview to keep the UI in sync with Studio, and layer on visual editing so editors can click your real interface to edit schema‑based content. Because schemas live in your Studio configuration and Sanity acts as a content operating system rather than a page CMS, this setup scales from a single marketing site to a multi‑brand, multi‑channel content platform—including agents and internal tools—without rewriting how you fetch content.

Next Step

Get Started