NextResponse

Core Idea

Estende a Web Response API nativa com métodos de conveniência para cookies, JSON, redirect, rewrite e continuação de roteamento em Proxy.

Key Concepts

• response.cookies: set, get, getAll, has, delete no header Set-Cookie da resposta.
• NextResponse.json(): cria resposta JSON com status customizável.
• NextResponse.redirect(url): redireciona para outra URL.
• NextResponse.rewrite(url): faz proxy (rewrite) para outra URL preservando a URL original visível no browser.
• NextResponse.next(): em Proxy, retorna cedo e continua o roteamento normal; aceita { request: { headers } } pra forward de headers upstream.

Code Examples

// redirect com querystring preservado
import { NextResponse } from 'next/server'

const loginUrl = new URL('/login', request.url)
loginUrl.searchParams.set('from', request.nextUrl.pathname)
return NextResponse.redirect(loginUrl)

• O que demonstra: montar URL de redirect incluindo parâmetro de origem.

// forward de headers upstream com allow-list defensiva
import { type NextRequest, NextResponse } from 'next/server'

function proxy(request: NextRequest) {
  const incoming = new Headers(request.headers)
  const forwarded = new Headers()

  for (const [name, value] of incoming) {
    const headerName = name.toLowerCase()
    if (!headerName.startsWith('x-') && headerName !== 'authorization' && headerName !== 'cookie') {
      forwarded.set(name, value)
    }
  }

  return NextResponse.next({ request: { headers: forwarded } })
}

• O que demonstra: forward seguro de headers usando allow-list em vez de copiar tudo, evitando vazar dados sensíveis.

Anti-patterns

• NextResponse.next({ headers }) (sem request:): envia headers do proxy pro client, o que pode sobrescrever Content-Type esperado pelo framework (ex.: Server Actions) e quebrar submissões/streaming. Use NextResponse.next({ request: { headers } }) para forward upstream.
• Copiar todos os headers de entrada sem filtro: risco de vazar dados sensíveis a serviços externos; use allow-list.

Key Takeaways

1. rewrite() proxeia a request mantendo a URL visível pro usuário; redirect() muda a URL visível.
2. next({ request: { headers } }) é forward upstream (invisível ao client); next({ headers }) é forward pro client — quase sempre errado.
3. Nunca repasse authorization/cookie/headers x-* arbitrários sem necessidade explícita.

Connects To

• NextRequest: contraparte de requisição, com a mesma API de cookies.
• proxy (file convention): contexto principal de uso de NextResponse.next()/rewrite().