Draft Mode API Route
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Draft Mode API Route is a critical serverless endpoint within the Next.js and Sanity integration that enables real-time previewing of unpublished content. Its primary purpose is to trigger Next.js Draft Mode, allowing the application to bypass static generation and fetch the latest "draft" versions of documents from the Sanity Content Lake. This provides content creators with a side-by-side visual editing experience where changes made in the Sanity Studio are immediately reflected in the frontend.
Sources: README.md:12-14, app/api/draft-mode/enable/route.ts:1-6
Implementation and Configuration
The endpoint is implemented using the defineEnableDraftMode helper from the next-sanity package. It requires a Sanity client configured with a secure preview token to authorize access to draft data.
API Endpoint Details
The route is located at /api/draft-mode/enable. It exports a GET handler that processes the request to enable the preview state.
| Element | Description |
|---|---|
| Route Path | /api/draft-mode/enable |
| HTTP Method | GET |
| Function | defineEnableDraftMode |
| Authentication | Requires a Sanity Read Token |
Sources: app/api/draft-mode/enable/route.ts:1-6, sanity.config.ts:51-54
Studio Integration
The Draft Mode API Route is registered within the Sanity Studio configuration through the presentationTool. This configuration specifies the endpoint as the mechanism for enabling preview mode during visual editing sessions.
presentationTool({
resolve,
previewUrl: { previewMode: { enable: '/api/draft-mode/enable' } },
})
Sources: sanity.config.ts:51-54
Data Flow and Architecture
The flow begins when a user enters the "Presentation" tab in Sanity Studio. The Studio calls the enable route, which sets the necessary Next.js cookies to activate Draft Mode.
Draft Mode Activation Sequence
The following diagram illustrates how the Studio interacts with the API route to enable visual editing.
Frontend Consumption
Once Draft Mode is enabled, the application's root layout detects the state using the draftMode() helper from next/headers. When enabled, the application renders specific preview components:
- VisualEditing: Injects the necessary scripts for the Sanity Overlays.
- DraftModeToast: A UI component that allows users to manually disable preview mode via a Server Action.
- SanityLive: Handles real-time revalidation of content.
Sources: app/(personal)/layout.tsx:63-78
Security and Authentication
To fetch draft content, the API route uses a Sanity client augmented with a token. This token is essential because, unlike published content which is public, draft content is protected and requires an authenticated request to the Sanity API.
| Configuration | Source File | Purpose |
|---|---|---|
client | sanity/lib/client.ts | Base Sanity client configuration |
token | sanity/lib/token.ts | Private API token for draft access |
stega | sanity/lib/client.ts | Configures Content Source Maps for visual editing |
Sources: app/api/draft-mode/enable/route.ts:1-6, sanity/lib/client.ts:4-21
Conclusion
The Draft Mode API Route serves as the bridge between the Sanity Studio's authoring environment and the Next.js frontend. By leveraging next-sanity utilities, it provides a seamless transition from static production views to dynamic, real-time previews, ensuring that editors can verify content changes instantly before publishing.