CMS for Next.js: preview and publication in 2026
Connect a CMS to Next.js with a clear draft and publication flow. Compare content access, previews and cache refresh before relying on updated store pages.
- Published
- Last updated
A CMS for Next.js needs a published-content query, an authenticated draft preview and a refresh path that reaches the customer page. Sanity is one documented option for that flow. Choose its integration for the router and cache model your store actually runs, then verify the policy version customers receive.
An editor seeing new text in preview proves only the preview works. Publication is complete when the approved record appears on the public storefront and any separate service that uses it for customer answers.
Choose the content and rendering approach
Choose the CMS connection against your Next.js router and deployment model. A client library helps you query content. It doesn’t decide which records are public or how a cached page refreshes.
Compare connection paths
| Connection | Where the request runs | What your team must connect |
|---|---|---|
| Sanity’s Next.js toolkit | Server Components and supporting route handlers | Queries, Studio preview and either automatic live updates or manual revalidation |
| A CMS content API | A server-side loader using HTTP or a supported client | Response mapping, authentication, preview and publication notifications |
| Build-time content query | During static page generation | CMS approval events to a successful build and deployed output |
The example below uses the App Router with manual fetching and revalidation, with Cache Components disabled. Next.js documents this cache model separately. Pages Router API routes use a different implementation. A static export also needs a build-and-release flow instead of request-time preview handlers.
Sanity also has defineLive for automatic updates. Its manual sanityFetch helper is a different function, despite sharing the name. Select one approach, because combining instructions for both can leave the page on an unintended refresh path.
Editorial policies and buying guides belong in the CMS. Keep prices, stock and orders in the commerce system that owns them. In the App Router, fetch private content in server code and pass only the required rendered content to the browser. Next.js’s data-fetching guide explains that server-side boundary.
If you’re still choosing a provider, compare headless CMS platforms first. For the difference between running content software and reading its API, use the JavaScript CMS guide.
Connect and render a published record
Use Sanity’s maintained App Router integration as the starting point. Its documented prerequisites include Node.js 22.12 or later, Next.js 16.x and next-sanity 13.1.5 or later. You also need a Sanity project with a dataset and a policy document schema.
Keep the project ID and dataset in configuration. Pin the API version supported by your application. Hold the Viewer token used for preview in the server-only SANITY_API_READ_TOKEN variable. A public dataset can return published content without that token. A private dataset needs authenticated reads on the server too.
Sanity’s client configuration reference explains these settings. Use useCdn: false for build-time reads and webhook-triggered revalidation so a refreshed page reads from the live API. Keep tokens out of variables prefixed with NEXT_PUBLIC_.
Map one policy to one route
Create a policy document type with slug, title, body and contentVersion. Map the returns slug to /policies/returns/. Use Sanity’s document identity and revision alongside your own content version for diagnosis.
Query the policy by type and slug, and select only those fields. Set perspective: 'published' explicitly for customer requests. The published perspective excludes draft-only records and unpublished edits.
For a fictional retailer, the normalised public result can look like this:
{
"policyId": "returns",
"slug": "returns",
"title": "Change-of-mind returns",
"body": "You can request a change-of-mind return within 14 days.",
"contentVersion": "returns-12"
}
These example terms don’t describe statutory consumer rights. The route renders the title and body, plus a small visible content-version label. Keep that label separate from any editorial publication date.
In app/policies/[slug]/page.tsx, await the route parameters and pass the slug as a query parameter. Validate the returned fields before rendering. A type generated from the schema helps development, but it doesn’t validate a network response.
Handle outcomes separately. Call notFound() when the published query returns no record, including a draft-only policy. Show the application’s error state when the request fails or the response is malformed. Don’t catch either failure and return an empty policy with a successful page status.
Preview drafts without publishing them
Use an authenticated preview route to enable Draft Mode for the editor’s browser session. In Sanity’s App Router integration, the Studio’s Presentation Tool calls /api/draft-mode/enable. The route uses defineEnableDraftMode from next-sanity/draft-mode with a server-authenticated client.
The helper validates the Studio preview request before enabling Draft Mode. Configure the Presentation Tool with that exact route and map the policy document to /policies/returns/. Add the frontend origin to the Sanity project’s allowed cross-origin settings with credentials enabled.
For the manual fetching approach, read (await draftMode()).isEnabled on the server. In an authorised preview, request the draft perspective with the read token and useCdn: false. Disable caching for that request and keep it outside the shared published-content cache.
Customer requests keep the published perspective. Disable source-map text encoding in metadata, even when a visual preview uses it in body text. Add the documented disable route so editors can leave Draft Mode.
Next.js’s Draft Mode guide explains the session cookie and cache bypass. The CMS query must still select the intended draft view. Enabling a cookie alone doesn’t change a published-only query into a draft query.
Test the separation with a fictional returns-13 draft that changes the period to 21 days. The editor’s preview must show 21 days and returns-13. A separate browser session without preview state must still show 14 days and returns-12.
Also try the preview route without valid authentication. It must reject the request without enabling Draft Mode. After the editor exits preview, reload the same policy route and confirm it shows the public version again.
Refresh and verify the customer-facing answer
Approval must trigger the refresh mechanism chosen for the public policy query. For this manual example, use a signed CMS webhook and path-based revalidation. Sanity’s webhook guide describes the handler and payload.
Store the webhook secret as server configuration in both systems. In the Next.js POST handler, use parseBody from next-sanity/webhook to validate the signature. Reject invalid requests, then validate the payload and allow only the expected policy routes before calling revalidatePath.
Configure the webhook to notify on published policy changes and send the affected route. Include unpublishing and deletion in the design so removed policies don’t remain publicly cached. Revalidation also needs to reach every page that repeats the policy, such as a buying guide with a returns summary.
For the fictional correction, publish returns-13, then confirm the published query contains the 21-day wording. After revalidation, request /policies/returns/ as a customer and compare its visible version and text with that record. A webhook’s successful response alone doesn’t prove the rendered page changed.
Diagnose an old policy in order
- Inspect the stale cache. Compare the live CMS result with the public route, then check the query’s cache settings and affected path. A CMS response cache can be stale independently of the Next.js cache.
- Inspect a rejected or missing notification. Check delivery status and signature validation, then confirm the payload maps to the actual customer route. Correct the cause before replaying the event.
- Inspect the active deployment. Confirm the release containing the handler and query configuration succeeded. For a build-based site, check that the policy-triggered build finished and that its output became the active release.
If you choose tags instead of paths, account for their refresh behaviour. revalidateTag with the max profile uses stale-while-revalidate semantics. A request can receive old content while background work refreshes it, so an immediate first response isn’t proof of the final version.
Finally, refresh any separate policy index or snapshot used by a shopping assistant. Ask a change-of-mind returns question and confirm its answer uses 21 days from returns-13. If the storefront and answer source disagree, hold the dependent answer until its source refreshes. The release check ends with the customer’s policy answer, not the CMS’s publish button.
Give your store its own shopping agent
Customers ask in their own words. Your agent finds, compares and checks out from your catalogue, right on your site.