Pular para o conteúdo
Documentação do Next.js PT-BR

Route Handlers

Route Handlers

Route Handlers permitem criar manipuladores de requisição personalizados para uma determinada rota, usando as APIs Web Request e Response.

Arquivo especial route.jsArquivo especial route.js

Bom saber: Route Handlers estão disponíveis apenas dentro do diretório app. Eles são o equivalente às API Routes do diretório pages, ou seja, você não precisa usar API Routes e Route Handlers juntos.

Convenção

Route Handlers são definidos em um arquivo route.js|ts dentro do diretório app:

app/api/route.ts
export async function GET(request: Request) {}

Route Handlers podem ser aninhados em qualquer lugar dentro do diretório app, da mesma forma que page.js e layout.js. Mas não pode haver um arquivo route.js no mesmo segmento de rota em que está o page.js.

Métodos HTTP aceitos

Os métodos HTTP a seguir são aceitos: GET, POST, PUT, PATCH, DELETE, HEAD e OPTIONS. Se um método não aceito for chamado, o Next.js retorna uma resposta 405 Method Not Allowed.

APIs estendidas NextRequest e NextResponse

Além de dar suporte às APIs nativas Request e Response, o Next.js as estende com NextRequest e NextResponse, com funções auxiliares práticas para casos de uso avançados.

Cache

Route Handlers não têm cache por padrão. Você pode, no entanto, optar por colocar em cache os métodos GET. Os outros métodos HTTP aceitos não têm cache. Para colocar em cache um método GET, use uma opção de configuração de rota, como export const dynamic = 'force-static', no arquivo do Route Handler.

app/items/route.ts
export const dynamic = 'force-static'

export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
  })
  const data = await res.json()

  return Response.json({ data })
}

Bom saber: os outros métodos HTTP aceitos não têm cache, mesmo no mesmo arquivo de um método GET com cache.

Com Cache Components

Quando Cache Components estão habilitados, os métodos GET dos Route Handlers seguem o mesmo modelo das rotas de UI normais do app. Por padrão, eles rodam em tempo de requisição, podem ser prerenderizados quando não acessam dados sem cache nem de runtime, e você pode usar use cache para incluir dados sem cache na resposta estática.

Exemplo estático - não acessa dados sem cache nem de runtime, então é prerenderizado no build:

app/api/project-info/route.ts
export async function GET() {
  return Response.json({
    projectName: 'Next.js',
  })
}

Exemplo dinâmico - acessa operações não determinísticas. Durante o build, o prerendering para quando Math.random() é chamado, e o rendering passa a acontecer na requisição:

app/api/random-number/route.ts
export async function GET() {
  return Response.json({
    randomNumber: Math.random(),
  })
}

Exemplo com dados de runtime - acessa dados específicos da requisição. O prerendering termina quando APIs de runtime como headers() são chamadas:

app/api/user-agent/route.ts
import { headers } from 'next/headers'

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

  return Response.json({ userAgent })
}

Bom saber: o prerendering para se o handler GET acessar requisições de rede, consultas a banco de dados, operações assíncronas de sistema de arquivos, propriedades do objeto de requisição (como req.url, request.headers, request.cookies, request.body), APIs de runtime como cookies(), headers(), connection(), ou operações não determinísticas.

Exemplo com cache - acessa dados sem cache (uma consulta a banco de dados), mas o coloca em cache com use cache, o que permite incluí-los na resposta com prerendering:

app/api/products/route.ts
import { cacheLife } from 'next/cache'

export async function GET() {
  const products = await getProducts()
  return Response.json(products)
}

async function getProducts() {
  'use cache'
  cacheLife('hours')

  return await db.query('SELECT * FROM products')
}

Bom saber: use cache não pode ser usado diretamente no corpo de um Route Handler. Extraia-o para uma função auxiliar. Respostas em cache são revalidadas conforme cacheLife quando chega uma nova requisição.

Route Handlers especiais

Route Handlers especiais, como sitemap.ts, opengraph-image.tsx e icon.tsx, e outros arquivos de metadados, permanecem estáticos por padrão, a menos que usem APIs que dependem da requisição ou opções de configuração dinâmicas.

Resolução de rotas

Considere route a primitiva de roteamento de nível mais baixo.

  • Ele não participa de layouts nem de navegações no cliente, como page faz.
  • Não pode haver um arquivo route.js na mesma rota que page.js.
PáginaRotaResultado
app/page.jsapp/route.js Conflito
app/page.jsapp/api/route.js Válido
app/[user]/page.jsapp/api/route.js Válido

Cada arquivo route.js ou page.js fica responsável por todos os verbos HTTP daquela rota.

app/page.ts
export default function Page() {
  return <h1>Hello, Next.js!</h1>
}

// Conflict
// `app/route.ts`
export async function POST(request: Request) {}

Leia mais sobre como os Route Handlers complementam o frontend, ou explore a Referência da API de Route Handlers.

Helper de contexto da rota

No TypeScript, você pode tipar o parâmetro context dos Route Handlers com o helper globalmente disponível RouteContext:

app/users/[id]/route.ts
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 })
}

Bom saber

  • Os tipos são gerados durante next dev, next build ou next typegen.

Referência da API

Saiba mais sobre Route Handlers