Support dynamic functions in Draft Mode in otherwise statically rendered pages

[angeloashmore]

Goals

1. Enhance Draft Mode by supporting cookies() or adding the ability to set and read serializable data while Draft Mode is enabled in normally statically rendered pages.
2. Retain the performance of static rendering except when in Draft Mode.

Non-Goals

1. The ability to use headers() or other router hooks (e.g. useSearchParams()) is not covered in this request, but could be enabled as a side-effect.
2. The behavior of static exports via next export is not expected to change as a result of this request.

Background

Preview Mode in the Pages Router allows a developer to pass data from an API Route via res.setPreviewData() to a page's getStaticProps(). This data container allows for passing arbitrary data to a page's data fetching function without the need to directly access headers, cookies, or any network request-level data.

Draft Mode works similarly to Preview Mode, but removes the capability of passing arbitrary data through its system. Instead, it assumes app code can be used to accomplish the same need. This assumption does not support an app that needs to access data in headers() or cookies() since it forces dynamic rendering; Draft Mode is designed for statically rendered pages, which don't allow dynamic functions.

As a specific example of this need, Prismic, a headless CMS, supports unlimited content branch previews using a cookie-based system. A Prismic-specific cookie contains a token referring to a specific content branch, which is sent along with Prismic API requests to query that branch of content. Prismic needs to read that cookie in order to query preview content, which forcibly opts the app into dynamic rendering at all times.

Proposal

The following two ideas could work:

1. Support all dynamic functions while Draft Mode is enabled.

Next.js could switch to full dynamic rendering when Draft Mode is enabled. Doing so would allow all dynamic functions to be used, including cookies(), headers(), and useSearchParams(), without forcing dynamic rendering while Draft Mode is disabled.

All other existing behavior protecting against dynamic rendering would be retained while Draft Mode is disabled, including export const dynamic = "error".

2. Add the ability to set and read data within Draft Mode’s system when enabled.

Replicating Preview Mode's data-storing behavior would allow for sending cookie, header, or arbitrary request-level data from a Route Handler to a page.

// src/app/enable-draft/route.ts

import { cookies, draftMode } from "next/headers";

export async function GET() {
  const cookieStore = cookies();
  const token = cookieStore.get("token");

  draftMode().enable({ token, foo: "bar" });

  return new Response("Draft mode is enabled");
}

Disabling Draft Mode would clear the stored data.

// src/app/disable-draft/route.ts

import { draftMode } from 'next/headers';
 
export async function GET(request: Request) {
  draftMode().disable();
  return new Response('Draft mode is disabled');
}

Draft Mode data could be returned from the draftMode() function.

// src/app/page.tsx

import { draftMode } from "next/headers";

export default function Page() {
  const { isEnabled, data } = draftMode();

  // Access data
  console.log(data.token);

  return <div>{/* ... */}</div>;
}

The data could be stored alongside the current store where Draft Mode’s enabled/disabled status is determined.

[jacobsfletch]

This feature is hugely needed by Payload as well. Accessing drafts requires authentication. This is done by setting an Authorization header on the request, which is derived from a cookie. This was trivial in the Pages Router, but not so much in the App Router. Adding support for "draftData" would fix this completely. One workaround I found was to use "Parallel Routes" to conditionally render my drafts as separate page entirely while keeping the same URL. It is not perfect, though, specifically in because it mixes static and dynamic imports and throws an error in development mode. I've described this is more details on the Next.js Discord server here: https://discord.com/channels/752553802359505017/1111410349246255165

[tom-sherman]

Is draft mode supposed to work as you describe when in dynamic mode? Because I can't get this to work, see #51302

[jacobsfletch]

^^ Update: as of v13.4.8 reading cookies at runtime from a static page is working as expected 🎉.

I was previously receiving this error: Page changed from static to dynamic at runtime /, reason: cookies. Now, I'm able to conditionally fetch draft data as expected, like this:

const { isEnabled: isDraftMode } = draftMode()
const page = !isDraftMode ? await fetchPage(slug) : await fetchDraftPage(slug) // `fetchDraftPage` calls `cookies()`

This also means that the Parallel Routes workaround is no longer needed. This is much simpler now 🙏

[nicholasio]

Wouldn't this force the page to be dynamic? or is Next.js smart enough to detect that cookies is only called in draftMode?

[angeloashmore]

Wouldn't this force the page to be dynamic? or is Next.js smart enough to detect that cookies is only called in draftMode?

Yes, it is smart enough to know when a dynamic function is called.

The following code ensures the page remains static unless draft mode is enabled:

const { isEnabled } = draftMode()

if (isEnabled) {
  const cookieJar = cookies()
  // Do something with cookies
}

Previously, this code would throw an error since the page was marked as static at build time. Now, Next.js can switch between the two runtime strategies.

[noisehunter82]

I support this proposal. Our application relies on 'setPreviewData()' in Preview API Route. We currently use Preview to display unpublished content by id in selected Contentful environment. 'setPreviewData()' is used to pass entry and environments ids as 'context.previewData' to the page component.
Without being able to pass serialised data on draftMode object we're facing a significant architectural change, and we're loosing an important feature.

[alyustik]

As a walkaround I've managed to get token from external draft class prototype, which is not good, buuut it helps keeping pages SSG and not opt out to SSR as it was before when you attempt to read token from the cookies at the page level (even not in a draft mode).

1. set cookies with token in /app/api/draft/route

const token = searchParams.get('token');
cookies().set('token', token);

2. then get it without using import {cookies} from 'next/headers'

export default function getPreviewToken() {
  const {isEnabled, _provider} = draftMode();
  return isEnabled ? _provider?._mutableCookies?._parsed?.get('token')?.value : undefined;
}

v14.0.4