Conceptual
4 min read

Draft Mode

Vercel's Draft Mode enables you to view your unpublished headless CMS content on your site before publishing it.
Table of Contents

Draft Mode, formerly Preview Mode, enables you to safely view your unpublished headless CMS content on your website rendered with all the normal styling and layout that you would see once published.

You can use Draft Mode if you:

  1. Use Incremental Static Regeneration (ISR) to fetch and render data from a headless CMS
  2. Want to view your unpublished headless CMS content on your site without rebuilding your pages when you make changes
  3. Want to protect your unpublished content from being viewed publicly

To use Draft Mode with projects hosted on Vercel, you must deploy your site with SvelteKit, Next.js, or a supported framework.

Draft Mode on Vercel is available anywhere the Vercel Toolbar is, including in production, localhost, and Preview Deployments.

Draft Mode was called Preview Mode prior to the release of Next.js 13.4 . The name was changed to avoid confusion with Preview Deployments , which are not the same.

To use Draft Mode with Next.js on Vercel, you must:

  1. Enable ISR on pages that fetch content. Using ISR is required on pages that you want to view in Draft Mode

  2. Add code to your ISR pages to detect when Draft Mode is enabled and render the draft content

  3. Enable Draft Mode with the Vercel toolbar in a Preview Deployment

    Next.js (/app)
    Next.js (/pages)
    app/page.tsx
    import { draftMode } from 'next/headers';
     
    async function getContent() {
      const { isEnabled } = draftMode();
     
      const contentUrl = isEnabled
        ? 'https://draft.example.com'
        : 'https://production.example.com';
     
      // This line enables ISR, required for draft mode
      const res = await fetch(contentUrl, { next: { revalidate: 120 } });
     
      return res.json();
    }
     
    export default async function Page() {
      const { title, desc } = await getContent();
     
      return (
        <main>
          <h1>{title}</h1>
          <p>{desc}</p>
        </main>
      );
    }

    See the Next.js docs to learn how to use Draft Mode with self-hosted Next.js projects:

To use Draft Mode with SvelteKit, see our dedicated SvelteKit docs.

You and your team members can toggle Draft Mode in the Vercel Toolbar in production, localhost, and Preview Deployments. When you do so, the toolbar will become purple to indicate Draft Mode is active.

The Vercel toolbar when Draft Mode is enabled.
The Vercel toolbar when Draft Mode is enabled.

Users outside your Vercel team cannot toggle Draft Mode.

If your Next.js version is <13.4, the Vercel Toolbar will turn purple when Draft Mode is enabled, but won't be able to toggle it on or off.

To share a draft URL, it must have the ?__vercel_draft=1 query parameter. For example:

https://my-site.com/blog/post-01?__vercel_draft=1

Viewers outside your Vercel team cannot enable Draft Mode or see your draft content, even with a draft URL.

Draft Mode allows you to bypass ISR caching to fetch the latest CMS content at request time. This is useful for seeing your draft content on your website without waiting for the cache to refresh, or manually revalidating the page yourself.

The process works like this:

  1. Each ISR route has a bypassToken configuration option, which is assigned a generated, cryptographically-secure value at build time
  2. When someone visits an ISR route with a bypassToken configured, the page will check for a __prerender_bypass cookie
  3. If the __prerender_bypass cookie exists and has the same value as the bypassToken your project is using, the visitor will view the page in Draft Mode

If you're viewing the page in a Preview Deployment on Vercel, only your Vercel team members will be able to view pages in Draft Mode.

Both Next.js and SvelteKit support Draft Mode.

Any framework that uses the Build Output API can support Draft Mode by adding the bypassToken option to prerender configuration.

Last updated on April 16, 2024