Static Site Generators in Production

Previewing Headless CMS Drafts

Editors who move from a traditional CMS to a headless one lose something they took for granted: the "Preview" button. In WordPress, preview renders the draft with the real theme instantly. On a static site backed by a headless CMS, the site is built from published content, so an unpublished draft is not in any build. Editors publish to see how a change looks, fix it, publish again, and occasionally ship a half-finished page to production because that was the only way to check the layout.

There are three ways to restore preview, from a zero-code second build to instant on-demand rendering. This guide explains each, how to connect the CMS's preview button to it, and how to keep draft content private. It is part of Preview Environments for Pull Requests.

Prerequisites

  • A static site pulling content from a headless CMS at build time — see Wiring a Headless CMS to a Static Build.
  • A CMS with a draft or preview API (Contentful, Sanity, Storyblok, Strapi, Hygraph and most others have one) and a preview token.
  • The ability to add a second deployment or a small amount of server code.

Three Approaches

Three ways to preview headless CMS drafts A draft build: a second deployment built with the draft API, rebuilt on each save; no code, but a wait of one build. On-demand preview routes: a few server-rendered routes fetch the draft and render it with the same templates; instant, needs an adapter. Live visual editing: the CMS embeds the preview and updates it as the editor types; best experience, most integration work. Effort against preview speed 1 · Draft build second deployment built with draft token webhook rebuilds on save no code changes waits one build per save small and mid-size sites 2 · On-demand routes /preview/[type]/[id] fetches draft per request same templates instant needs server adapter most teams' best balance 3 · Live visual editing preview inside the CMS updates as you type click-to-edit overlays best editor experience CMS-specific integration marketing-heavy teams
Most teams start with a draft build and move to on-demand routes when editors ask for speed.

Approach 1: A Draft Build

Create a second deployment of the same repository — a separate Cloudflare, Netlify or Vercel project, or a separate environment — with two differences: it uses the CMS preview token, which returns drafts, and it is protected and marked noindex.

// src/lib/cms.js
const isDraft = process.env.CONTENT_MODE === 'draft';
export const client = createClient({
  space: process.env.CMS_SPACE,
  accessToken: isDraft ? process.env.CMS_PREVIEW_TOKEN : process.env.CMS_DELIVERY_TOKEN,
  host: isDraft ? 'preview.cms.example.com' : 'cdn.cms.example.com',
});

Point a CMS webhook at the draft deployment's build hook so every save triggers a rebuild, and set the CMS's preview URL template to the draft site, for example https://drafts.example.com/blog/{slug}/. Editors click Preview, wait for the build, and see the page with the real templates.

The weakness is speed. A two-minute build means a two-minute wait after every change, and many saves in quick succession queue builds. Debounce the webhook, or use a build hook that cancels superseded builds; see Netlify Build Hooks for Content Updates.

Approach 2: On-Demand Preview Routes

Most generators can mix static pages with a few server-rendered routes. Keep every public page static and add one preview route that fetches a draft from the CMS on each request and renders it with the same layout components.

In Astro with a server adapter, mark one page as on-demand:

---
// src/pages/preview/[type]/[id].astro
export const prerender = false;
import { getDraft } from '../../../lib/cms';
import ArticleLayout from '../../../layouts/ArticleLayout.astro';

const secret = Astro.url.searchParams.get('secret');
if (secret !== import.meta.env.PREVIEW_SECRET) return new Response('Not found', { status: 404 });

const entry = await getDraft(Astro.params.type, Astro.params.id);
if (!entry) return new Response('Not found', { status: 404 });
Astro.response.headers.set('X-Robots-Tag', 'noindex');
Astro.response.headers.set('Cache-Control', 'private, no-store');
---
<ArticleLayout entry={entry} />

The CMS preview URL becomes https://www.example.com/preview/article/{id}?secret=.... The preview is instant because nothing is built — one CMS request, one render. Next.js offers the same pattern with draft mode, which sets a cookie so the normal page routes render drafts for that browser. Eleventy and Hugo, which have no request-time rendering, can reach the same result with an edge function that fetches the draft and renders it with a shared template engine, though that means maintaining templates in two places.

Request flow for an on-demand preview route The editor clicks Preview in the CMS, which opens the preview route with the entry id and a secret. The route validates the secret, fetches the draft from the CMS preview API using a server-side token, renders it with the production layout, and returns it with noindex and no-store headers. Public pages continue to be served from static files. One click, one render, no build CMS editor clicks Preview /preview/article/{id} check secret render with ArticleLayout CMS preview API server-side token only response headers X-Robots-Tag: noindex · no-store every public page is still a static file; only /preview/* runs code
The preview uses the production layout, so what editors see is what will ship.

Approach 3: Live Visual Editing

Several CMSs now offer visual editing: the preview is embedded in the CMS, updates as the editor types, and overlays let editors click a heading on the page to jump to its field. Sanity's Presentation tool, Storyblok's Visual Editor and Contentful's Live Preview all work this way. They build on approach 2 — an on-demand route that renders drafts — and add a small client script that listens for content changes and re-renders. The integration is CMS-specific and adds client JavaScript to the preview route only, never to public pages. Because the preview is embedded in the CMS in an iframe, the preview route must allow framing by the CMS origin with a Content-Security-Policy: frame-ancestors header on preview responses only, while public pages keep denying it. Budget time for this integration: it touches the CMS configuration, the preview route and the content model, and it is easiest to add once the plain on-demand route is working.

Choosing Between Them

The deciding factor is usually how often editors preview. A documentation team that publishes a few pages a week and previews each once is well served by a draft build; a two-minute wait a few times a week costs little. A marketing team iterating on a landing page previews dozens of times an hour, and every minute of waiting is a minute of lost flow — on-demand routes pay for themselves within days.

Time from save to visible preview by approach For a 1,200-page site, a draft build takes about 90 seconds from save to preview. An on-demand preview route takes under one second. Live visual editing updates in about 200 milliseconds as the editor types. Save-to-preview time, 1,200-page site draft build ≈ 90 s on-demand route < 1 s live visual editing ≈ 0.2 s, while typing bar length is proportional to time
The first step from a build to a request-time render removes almost all the waiting.

Hosting constraints matter too. On-demand routes need an adapter and a host that runs server code — Cloudflare, Netlify, Vercel and most others do. A site deployed to plain object storage with no edge compute is limited to the draft build, or to a preview route hosted separately on a platform that can run it.

Keeping Drafts Private

Draft content is often the most sensitive content a site has: unannounced products, embargoed news, pricing changes. Whatever approach you use:

  • Keep the preview token server-side. It must never appear in client JavaScript or in the static build of public pages.
  • Require a secret. The CMS preview link should carry a secret the route validates, or the route should sit behind authentication. Rotate the secret if it leaks.
  • Protect draft deployments. Put the whole draft site behind SSO; see Password-Protecting Preview Deployments.
  • Send noindex and no-store on every draft response, so neither search engines nor CDNs keep a copy.

Measured Impact

A marketing team using Contentful and Astro had no preview; editors published to check layouts and reverted about one change in twelve. The team first added a draft build, which editors used but found slow at about 90 seconds per save. They then added an on-demand preview route with the Cloudflare adapter, reusing the production layouts. Preview time dropped to under a second, reverted publishes fell from about one in twelve to one in eighty over the next quarter, and public pages remained fully static with no change in Core Web Vitals.

Pitfalls & Rollback

  • Separate preview templates. Previews rendered with different code drift from production; always reuse the real layouts.
  • Token in the client bundle. Check the built output for the preview token string in CI.
  • Caching drafts. A CDN that caches a preview response can serve drafts to others; send no-store.
  • References to unpublished entries. Drafts often link to other drafts; the preview fetch must request linked entries from the preview API too.
  • Rollback: point the CMS preview URL back to the draft build, or remove it; public pages are unaffected.

Conclusion

Static sites can give editors a real preview button. A draft build is the zero-code option, an on-demand preview route is instant and reuses production templates, and live visual editing adds in-CMS editing on top. Whichever you choose, keep the preview token on the server, require a secret or authentication, send noindex and no-store, and render with the same components as the live site so preview and production never disagree.

FAQ

Why is previewing drafts hard on a static site?

A static site is built ahead of time from published content, so an editor's unpublished changes are not in any build. Seeing a draft means either building a separate site that includes drafts, or rendering the draft on request with a small amount of server code.

What is the simplest way to preview CMS drafts?

A second deployment of the same site that builds with the CMS draft or preview API token and is rebuilt by a webhook whenever content is saved. It needs no code changes beyond an environment switch, but each preview waits for a build.

How do I get instant draft previews without a server?

Most hosts let a static site include a few on-demand routes - Astro server islands or on-demand pages with an adapter, Next.js draft mode, or an edge function - that fetch the draft from the CMS preview API and render it with the same templates, while every other page stays static.

How do I keep draft content private?

Use the CMS's preview token only on the server side, never in client JavaScript, require a signed or secret preview link from the CMS, protect the draft deployment with authentication, and send noindex on every draft response.