cookies

Core Idea

cookies é uma função assíncrona para ler cookies de request recebidos em Server Components, e ler/escrever cookies de response em Server Functions ou Route Handlers.

Key Concepts

• await cookies(): retorna um cookie store; deve ser usado com async/await ou use() do React.
• Assíncrona desde a v15: em versões 14 e anteriores era síncrona; ainda acessível sincronamente por compatibilidade, mas comportamento será depreciado.
• Request-time API: usar cookies() em layout/page opta a rota por dynamic rendering; com Cache Components, chamar fora de <Suspense> impede o prerender.
• Leitura vs escrita: ler funciona em Server Components (dado já veio no header da requisição); escrever (.set/.delete) só funciona em Server Function ou Route Handler, pois exige Set-Cookie no response header antes do streaming começar.
• .delete(): só pode ser chamado em Server Function/Route Handler, e só se pertencer ao mesmo domínio/protocolo de onde .set foi chamado.

Code Examples

import { cookies } from 'next/headers'

export default async function Page() {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

• O que demonstra: leitura de um cookie em Server Component.

'use server'
import { cookies } from 'next/headers'

export async function create(data) {
  const cookieStore = await cookies()
  cookieStore.set('name', 'lee', { secure: true })
}

• O que demonstra: escrita de cookie dentro de Server Function, com opção secure.

'use server'
import { cookies } from 'next/headers'

export async function deleteCookie(data) {
  const cookieStore = await cookies()
  cookieStore.delete('name')
}

• O que demonstra: uma das três formas de deletar cookie (.delete(); alternativas: setar valor vazio, ou maxAge: 0).

Reference Tables

Método	Retorno	Descrição
get('name')	Object	cookie por nome
getAll()	Array	todos os cookies com nome correspondente (ou todos, se omitido)
has('name')	Boolean	existe o cookie?
set(name, value, options)	-	define cookie de saída
delete(name)	-	remove cookie
toString()	String	representação em string

Option	Type	Description
expires	Date	data exata de expiração
maxAge	Number	vida útil em segundos
domain	String	domínio de escopo
path	String, default '/'	escopo de caminho
secure	Boolean	só HTTPS
httpOnly	Boolean	inacessível via JS client
sameSite	Boolean/'lax'/'strict'/'none'	comportamento cross-site
priority	'low'/'medium'/'high'	prioridade do cookie
partitioned	Boolean	cookie particionado (CHIPS)

Anti-patterns

• Tentar .set()/.delete() durante render de Server Component: não funciona; cookies só são persistidos via header de response em Server Function/Route Handler.
• Usar <Link> com prefetch para rota que deleta cookie: o prefetch pode disparar a requisição e apagar o cookie sem intenção; passe prefetch={false}.

Key Takeaways

1. cookies() opta a rota por rendering dinâmico; combine com <Suspense> sob Cache Components para não bloquear o prerender inteiro.
2. Para refletir mudança de cookie na UI e nos dados numa mesma ida ao servidor, use cookies().set() dentro de uma Server Action ligada a um form.
3. Para revalidar dados cacheados após alterar um cookie, chame revalidatePath ou revalidateTag explicitamente.

Connects To

• draftMode: usa cookie especial __prerender_bypass internamente, semelhante em padrão de uso a cookies().
• headers: outra Request-time API com as mesmas implicações de dynamic rendering.
• Cache Components / Suspense: padrão para isolar leitura de cookies sem perder prerender do resto da página.