Capítulo 158 de 456

draftMode

Core Idea

draftMode é uma função assíncrona para habilitar, desabilitar e checar o Draft Mode em Server Components, permitindo que editores pré-visualizem conteúdo não publicado de um CMS headless burlando o cache do Next.js.

Key Concepts

  • await draftMode(): retorna objeto com isEnabled, enable() e disable().
  • Assíncrona desde a v15: em versões 14 e anteriores era síncrona; comportamento síncrono ainda funciona por compatibilidade, mas será depreciado.
  • enable(): só pode ser chamado em Route Handler; define o cookie __prerender_bypass. Um novo valor de bypass é gerado a cada next build.
  • disable(): remove o cookie; por padrão a sessão de Draft Mode termina ao fechar o navegador.
  • Dentro de use cache: isEnabled é legível dentro de um escopo de diretiva de cache; cookies()/headers() não são, mesmo com Draft Mode ativo.
  • Efeito no cache: quando Draft Mode está ativo, todas as funções/componentes sob escopo de cache re-executam a cada requisição e não são salvos em cache.
  • Chamar enable()/disable() dentro de escopo de cache: lança erro.

Code Examples

import { draftMode } from 'next/headers'

export async function GET(request: Request) {
  const draft = await draftMode()
  draft.enable()
  return new Response('Draft mode is enabled')
}
  • O que demonstra: habilitar Draft Mode via Route Handler.
import { draftMode } from 'next/headers'

export default async function Page() {
  const { isEnabled } = await draftMode()
  return (
    <main>
      <p>Draft Mode is currently {isEnabled ? 'Enabled' : 'Disabled'}</p>
    </main>
  )
}
  • O que demonstra: checar o estado do Draft Mode dentro de um Server Component.

Reference Tables

MethodDescription
isEnabledboolean indicando se Draft Mode está ativo
enable()habilita via cookie __prerender_bypass (em Route Handler)
disable()remove o cookie (em Route Handler)

Anti-patterns

  • Chamar enable()/disable() dentro de escopo use cache: lança erro.
  • Linkar para rota de disable com prefetch ligado: pode desabilitar o Draft Mode acidentalmente no prefetch; use prefetch={false}.
  • Testar Draft Mode localmente sobre HTTP sem permitir cookies de terceiros: o browser precisa aceitar third-party cookies/local storage.

Key Takeaways

  1. Draft Mode força re-execução (sem cache) de todo conteúdo sob escopo use cache, garantindo dados sempre frescos para o editor.
  2. O cookie de bypass é regenerado a cada build, então não pode ser adivinhado entre deploys.
  3. isEnabled é a única leitura de estado de Draft Mode permitida dentro de um escopo de cache directive.

Connects To

  • cookies: draftMode usa cookies internamente (__prerender_bypass) com as mesmas restrições de leitura/escrita.
  • use cache: define os limites do que pode ou não ser lido/chamado sob Draft Mode.
AnteriorcookiesPróximofetch