Capítulo 169 de 456

NextRequest

Core Idea

Estende a Web Request API nativa com métodos de conveniência para cookies e uma URL parseada (nextUrl), usado em Route Handlers e Proxy.

Key Concepts

  • request.cookies: interface para ler/mutar o header Set-Cookie da requisição (set, get, getAll, delete, has, clear).
  • request.nextUrl: estende URL nativo com propriedades específicas do Next.js: basePath, buildId, pathname, searchParams.

Code Examples

// cookies
request.cookies.set('show-banner', 'false')
request.cookies.get('show-banner')
request.cookies.getAll('experiments')
request.cookies.delete('experiments')
request.cookies.has('experiments')
request.cookies.clear()
  • O que demonstra: API completa de manipulação de cookies de request.
// nextUrl
request.nextUrl.pathname // /home
request.nextUrl.searchParams // { name: 'lee' } para /home?name=lee
  • O que demonstra: acesso direto a pathname e searchParams sem parsear a URL manualmente.

Reference Tables

PropertyTypeDescription
basePathstringbasePath configurado
buildIdstring | undefinedidentificador do build
pathnamestringpathname da URL
searchParamsObjectquery params
VersionChanges
v15.0.0ip e geo removidos

Anti-patterns

  • Usar propriedades de internacionalização do Pages Router: não disponíveis no App Router via nextUrl.

Key Takeaways

  1. NextRequest é o tipo padrão do primeiro argumento em Proxy e em GET/POST de Route Handlers quando tipado explicitamente.
  2. Prefira nextUrl a fazer new URL(request.url) manualmente, já traz pathname/searchParams prontos.

Connects To

  • NextResponse: contraparte de resposta, com os mesmos métodos de cookies.
  • proxy (file convention): onde NextRequest é mais usado para inspecionar/roteiar requests.
AnteriorioPróximoNextResponse