Capítulo 127 de 456

route.js

Core Idea

Route Handlers criam handlers de request customizados por rota usando as Web APIs Request/Response, servindo como a alternativa a page.js quando você quer expor uma API em vez de UI num segmento.

Key Concepts

  • HTTP methods suportados: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS (cada um exportado como função nomeada); OPTIONS é implementado automaticamente se não definido.
  • request param: instância de NextRequest, extensão da Web Request com nextUrl e cookies convenientes.
  • context.params: promise com os dynamic route params do segmento atual (desde v15, é assíncrono).
  • RouteContext<Route>: helper de tipo global (gerado por next dev/build/typegen) para tipar params a partir da rota literal.
  • Segment config: mesmas opções de page/layout (dynamic, dynamicParams, revalidate, fetchCache, runtime, preferredRegion).

Code Examples

import type { NextRequest } from 'next/server'

export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) {
  const { id } = await ctx.params
  return Response.json({ id })
}
  • O que demonstra: leitura tipada de params via RouteContext sem imports manuais de tipo.
export async function GET(request: Request) {
  return new Response('Hello, Next.js!', {
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  })
}
  • O que demonstra: CORS por Route Handler individual usando headers padrão da Web API.
export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
  • O que demonstra: as opções de Route Segment Config disponíveis em um route.ts.

Reference Tables

RouteExample URLparams
app/dashboard/[team]/route.js/dashboard/1Promise<{ team: '1' }>
app/shop/[tag]/[item]/route.js/shop/1/2Promise<{ tag: '1', item: '2' }>
app/blog/[...slug]/route.js/blog/1/2Promise<{ slug: ['1', '2'] }>

Anti-patterns

  • Usar bodyParser ou config extra como no Pages Router: Route Handlers da App Router não precisam disso — leia o body com request.json(), .text() ou .formData() diretamente.
  • Reimplementar sitemap.xml/robots.txt/ícones via Route Handler quando já existe suporte nativo: prefira os metadata file conventions, que já geram esses arquivos.
  • Esperar cache estático padrão em GET: desde v15.0.0-RC, o cache padrão de handlers GET mudou de estático para dinâmico.

Key Takeaways

  1. context.params é uma promise desde a v15 — sempre await.
  2. Para múltiplos Route Handlers com CORS, prefira configurar centralizado via proxy.js ou headers do next.config.js em vez de repetir em cada rota.
  3. generateStaticParams combinado com Route Handlers dinâmicos permite gerar algumas respostas em build time e outras em request time; com Cache Components, combine com use cache.
  4. Streaming de resposta funciona tanto via SDKs (AI SDK) quanto via ReadableStream nativo.

Connects To

  • page.js: alternativa para UI no mesmo segmento; um segmento não pode ter page.js e route.js simultaneamente.
  • route-segment-config: opções compartilhadas de cache/runtime/região.
  • cookies() / headers(): funções de next/headers usadas dentro de Route Handlers.
AnteriorpublicPróximodynamicParams