headers

Core Idea

Função async para ler os headers HTTP da requisição de entrada dentro de um Server Component.

Key Concepts

• headers(): não recebe parâmetros; retorna um objeto Headers (Web API) somente leitura.
• Read-only: não é possível set/delete headers de saída com essa função.
• Request-time API: opta a rota por dynamic rendering, já que o valor não pode ser conhecido antecipadamente.

Code Examples

// app/page.tsx
import { headers } from 'next/headers'

export default async function Page() {
  const headersList = await headers()
  const userAgent = headersList.get('user-agent')
}

• O que demonstra: leitura básica de um header via .get().

// app/page.js - forward de Authorization
import { headers } from 'next/headers'

export default async function Page() {
  const authorization = (await headers()).get('authorization')
  const res = await fetch('...', {
    headers: { authorization },
  })
  const user = await res.json()
  return <h1>{user.name}</h1>
}

• O que demonstra: repassar o header Authorization recebido para outra chamada fetch.

Reference Tables

Método	Descrição
entries()	iterator de todos os pares chave/valor
forEach()	executa função para cada par
get()	retorna string com valores de um header
has()	boolean se o header existe
keys()	iterator das chaves
values()	iterator dos valores

Version	Changes
v15.0.0-RC	headers virou função async (havia codemod)
v13.0.0	headers introduzido

Anti-patterns

• Chamar headers() fora de Suspense com Cache Components: impede o prerender da rota — ver mensagem "blocking-prerender-runtime".

Key Takeaways

1. Sempre await headers() — em v14 e anteriores era síncrono, hoje é async (compat retrocompatível em v15 mas deprecated).
2. Uso de headers() força dynamic rendering na rota.
3. Read-only: para mutar headers de resposta use NextResponse em Route Handlers/Proxy.

Connects To

• NextRequest: alternativa quando trabalhando dentro de Proxy/Route Handlers, com métodos de cookie e URL.
• cookies(): API irmã para leitura de cookies de request.