Capítulo 302 de 456

Draft Mode

Core Idea

Draft Mode faz Next.js pular Static Generation pra páginas específicas e renderizar em request time com conteúdo de rascunho (draft) de um headless CMS, em vez do conteúdo publicado.

Key Concepts

  • res.setDraftMode({ enable: true }): chamado numa API Route, seta cookie __prerender_bypass que ativa Draft Mode nas requests seguintes.
  • context.draftMode: dentro de getStaticProps, fica true quando o cookie está presente, permitindo buscar dado de rascunho em vez do publicado.
  • Draft URL segura: fluxo recomendado usa secret token + slug na query string, validado na API route antes de habilitar o modo e redirecionar (307) evitando open redirect.
  • res.setDraftMode({ enable: false }): limpa o cookie manualmente; se disparado via next/link, precisa prefetch={false} pra não apagar o cookie sem querer.
  • Funciona com getServerSideProps e API Routes: context.draftMode e req.draftMode respectivamente.
  • Cookie único por build: novo bypass cookie gerado a cada next build, impedindo que seja adivinhado.

Code Examples

export default async (req, res) => {
  if (req.query.secret !== 'MY_SECRET_TOKEN' || !req.query.slug) {
    return res.status(401).json({ message: 'Invalid token' })
  }
  const post = await getPostBySlug(req.query.slug)
  if (!post) {
    return res.status(401).json({ message: 'Invalid slug' })
  }
  res.setDraftMode({ enable: true })
  res.redirect(post.slug)
}
  • O que demonstra: validação de secret+slug antes de ativar draft mode e redirect seguro (nunca usar req.query.slug cru no redirect).
export async function getStaticProps(context) {
  const url = context.draftMode
    ? 'https://draft.example.com'
    : 'https://production.example.com'
  const res = await fetch(url)
}
  • O que demonstra: alternar endpoint de fetch conforme context.draftMode.

Anti-patterns

  • Redirecionar direto pra req.query.slug: abre vulnerabilidade de open redirect; sempre redirecionar pro slug retornado pelo CMS após validação.
  • Setar Cache-Control em rota com Draft Mode: o cache não pode ser bypassed nesse caso; usar ISR em vez disso.
  • Apagar o cookie via next/link sem prefetch={false}: o prefetch dispara a rota de disable acidentalmente.

Key Takeaways

  1. Draft Mode é o mecanismo certo pra preview de conteúdo de CMS sem abandonar Static Generation nas demais páginas.
  2. Sempre validar secret+slug no servidor antes de habilitar o modo, nunca confiar em input do client pro redirect.
  3. context.draftMode funciona tanto em getStaticProps quanto em getServerSideProps; API Routes usam req.draftMode.
  4. Testar localmente por HTTP exige que o browser permita cookies/local storage de terceiros.

Connects To

  • ch318 Preview Mode: nome anterior/equivalente conceitual ao Draft Mode em versões antigas do Pages Router.
  • ch305 ISR: alternativa de cache pra conteúdo que muda com frequência sem precisar de Draft Mode.
AnteriorDebuggingPróximoEnvironment Variables