CMS Preview Should Be a Migration Requirement, Not an Afterthought

CMS preview should be treated as a migration requirement because it is how editors decide whether the platform can be trusted.

It is easy to leave preview until late. The public site renders. The CMS has content. The migration checklist is crowded. Preview feels like an integration detail that can be wired up after the main route work.

That is backwards. Preview is where content model decisions, authentication, cookies, iframe policy, draft data, cache invalidation, route handling, and editorial workflow all meet. If those decisions are wrong, the new site may look finished while editors still approve content through screenshots, copied URLs, and guesswork.

For teams moving to Next.js, changing CMS, or rebuilding a headless front end, preview belongs in the architecture from day one.

Preview Defines the Draft Contract

The first question is not "how do we enable preview?" It is "what does preview promise?"

A useful preview contract says which content state editors can see, which document types can be previewed, how unpublished references behave, which environment is used, and what the editor sees when a draft cannot render safely.

That contract needs to cover:

• draft page content
• published page content
• unpublished linked entries
• shared modules
• navigation and global content
• missing slugs
• validation errors
• environment‑specific content
• supporting documents that do not have their own route

The existing article on Preview Mode in Next.js with a headless CMS covers the earlier implementation pattern. The migration question is broader: what should editors be able to trust before launch?

Draft Mode is the Mechanism, Not the Workflow

Next.js Draft Mode is important, but it is not the whole feature.

The Next.js Draft Mode API lets the application enable, disable, and check draft state for a browser session. Vercel's Draft Mode documentation frames the hosting workflow around viewing unpublished CMS content while preserving static production behaviour.

Those mechanisms still need product decisions around:

• preview URL validation
• secret handling
• authentication
• route resolution
• draft data fetching
• cache bypassing
• error states
• editor entry points
• environment ownership

If Draft Mode is wired up but the route still fetches published data, preview lies. If the route fetches draft data for the main entry but not for linked entries, preview half‑lies. If the route fails silently and falls back to published content, preview becomes actively dangerous.

Preview URLs Should Be Boring and Safe

Preview URLs are part of the platform contract.

A good preview URL should identify the content, prove the request is allowed, and route the editor to the right page without becoming an open redirect or a vague catch‑all. It should not trust arbitrary paths from query strings. It should validate the document type, slug, environment, and whether the requested document maps to a renderable route.

This becomes more important during migration because route structures and content models are often changing at the same time. A Contentful page entry might become a Sanity document. A Gatsby route might become a Next.js dynamic route. A shared component might move from a referenced entry into a nested object.

If the preview URL model is not designed early, teams often patch it separately for each content type. That works briefly, then becomes the next source of editorial confusion.

Iframes Expose Cookie and Header Decisions

Many CMS preview tools use embedded previews. That makes browser policy part of the system.

Cookies that work in a normal tab may behave differently inside an iframe. The MDN documentation for Set‑Cookie and SameSite is a useful reminder that cookie attributes affect cross‑site and embedded contexts. Preview routes also need frame policy decisions. The MDN documentation for Content Security Policy frame-ancestors explains the directive that controls which parents may embed a page.

The answer is not to weaken security headers until preview works. The answer is to decide:

• which CMS origins may embed preview
• which environments support embedded preview
• how preview authentication behaves in an iframe
• whether third‑party cookie restrictions affect the flow
• whether a new‑tab preview is safer for some content types

Preview failures often look random because cookie, auth, frame, and environment rules are tested separately. Editors experience them as one broken feature.

Visual Editing Needs Even Clearer Boundaries

Sanity visual editing and similar tools can be very useful, but they raise the bar for preview planning.

Sanity's Visual Editing documentation describes live editing as a bridge between Studio and the website. The architecture includes content source maps, overlays, live updates, preview mode, and the Presentation Tool. That is powerful, but it is not magic.

Before promising visual editing, decide which pages and components can support it cleanly. Some content is directly editable. Some is transformed before rendering. Some is assembled from several documents. Some appears in multiple places. Some is hidden behind interaction or personalisation.

If visual editing is a migration goal, test it with real content shapes, not a demo article.

Cache Invalidation Has to Include Preview Thinking

Preview and published freshness are related, but they are not the same.

Public pages may use static generation, ISR, cache tags, CDN caching, or webhook‑triggered revalidation. Preview should usually bypass some of that so editors can see current draft content. The two paths need to be understood separately.

A migration plan should state:

• which requests use published cache
• which preview requests bypass cache
• which shared data is still cached in preview
• how draft content is fetched
• how published content is invalidated
• what happens after publish
• how stale preview states are detected

If editors publish and the public page stays stale, preview trust suffers even if preview itself is technically correct. If preview bypasses everything and becomes painfully slow, editors stop using it. The right design balances accuracy, speed, and operational clarity.

Preview Should Support Governance, Not Bypass It

Preview is part of release governance.

In a migration, teams need to know who can preview unpublished content, who can share preview URLs, which environments are safe for client review, whether preview exposes sensitive drafts, and how long preview sessions last. Those decisions matter for legal, commercial, and editorial reasons.

This is especially true for projects involving a Contentful to Sanity migration or wider headless CMS integration, because the migration may temporarily leave two systems capable of holding draft content. Governance should make source of truth, access, and approval state clear.

If preview is treated as a developer convenience, governance becomes informal. Informal preview rules do not survive launch pressure.

Test Preview through Real Editorial Paths

Do not validate preview by hitting a route manually and checking that Draft Mode turns on.

Open the CMS. Use the editor's preview action. Test the content types editors use most. Test unpublished references, missing fields, new slugs, renamed slugs, scheduled content, environment‑specific content, shared modules, iframe preview, new‑tab preview, protected deployments, and publish‑to‑live behaviour.

For Contentful‑specific issues, the article on fixing Contentful preview in Next.js goes through cookies, iframes, auth, routes, and editor trust in more detail. The same principle applies more broadly: preview should be tested through the path editors actually use.

Wrapping Up

CMS preview is not a finishing touch on a Next.js migration.

It is the visible expression of several platform decisions: draft state, routing, authentication, cookies, iframe policy, cache invalidation, content modelling, validation, and release governance. If preview is added late, it usually reveals decisions that should have been made earlier.

Treat preview as a migration requirement. Define the contract, design the URLs, test the editor path, and make failure states honest. Editors should not have to guess whether the page they are approving is real.

Key Takeaways

• Preview is an editorial trust requirement, not just a technical toggle.
• Draft Mode enables preview sessions, but the workflow needs separate design.
• Preview URLs, auth, cookies, iframes, and cache behaviour must be planned together.
• Visual editing should be tested with real content models before it is promised.
• Migration governance should define who can preview, share, approve, and publish draft content.