Setting up Next.js Draft Mode

Static rendering is useful when your pages fetch data from a headless CMS. However, it’s not ideal when you’re writing a draft on DatoCMS and want to view the draft immediately on your page.

Next.js has a feature called Draft Mode, which solves this problem. Here’s a guide on how to use it.

(Applies to Next.js 15.x and 16.x)

Step 1: Create a draft mode API route

First, create a route handler that enables draft mode. It can have any name — e.g. app/api/draft-mode/enable/route.ts. In this route handler, you must call (await draftMode()).enable() to enable draft mode.

To keep drafts private, protect the route with a secret token. To support Visual Editing, also accept a redirect parameter with the path to load:

1
import { draftMode } from 'next/headers';
2
import { redirect } from 'next/navigation';
3
import type { NextRequest } from 'next/server';
4

5
export async function GET(request: NextRequest) {
6
  const token = request.nextUrl.searchParams.get('token');
7
  const redirectTo = request.nextUrl.searchParams.get('redirect') || '/';
8

9
  // Ensure that the request comes from a trusted source
10
  if (token !== process.env.SECRET_API_TOKEN) {
11
    return new Response('Invalid token', { status: 401 });
12
  }
13

14
  // Avoid open redirects: only follow paths on this same host
15
  if (new URL(redirectTo, request.url).hostname !== request.nextUrl.hostname) {
16
    return new Response('URL must be relative!', { status: 422 });
17
  }
18

19
  const draft = await draftMode();
20
  draft.enable();
21

22
  redirect(redirectTo);
23
}

You can manually test this route by accessing it via a browser at http://localhost:3000/api/draft-mode/enable?token=<SECRET_API_TOKEN>. You’ll notice that you'll be redirected to the homepage, and the __prerender_bypass cookie will be set.

To exit draft mode, create a similar route that calls (await draftMode()).disable().

Step 2: Conditionally include draft records

Once draft mode is set up, your pages can check whether it is active with the isEnabled property of await draftMode(). Use it to turn on the includeDrafts flag in the call to performRequest.

This will instruct DatoCMS to return records at their latest version available instead of the currently published one:

1
import { draftMode } from 'next/headers';
2

3
export default async function Page() {
4
  const { isEnabled } = await draftMode();
5

6
  const { data: { homepage } } = await performRequest(PAGE_CONTENT_QUERY, {
7
    includeDrafts: isEnabled,
8
  });
9

10
  // [...]
11
}

You can read more details regarding draft mode on the Next.js docs page.