Tipagem de Route Handlers

Q: Quais exportações de métodos HTTP um arquivo de route handler suporta?

GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS Exporte cada um como uma função assíncrona nomeada no arquivo route.ts.

Q: Por que request.json() é tipado como Promise e o que devo fazer a respeito?

A API Web Request.json() não tem como conhecer a forma do seu payload em tempo de compilação. Sempre valide ou restrinja o resultado antes de usá-lo (type guard, Zod, ou conversão explícita após verificações).

Q: Como tipar parâmetros de rota dinâmicos no Next.js 15?

Os parâmetros são envolvidos em uma Promise e devem ser aguardados.

Q: Armadilha: O que acontece se eu esquecer de await os params no Next.js 15?

Você recebe um objeto Promise em vez dos params reais. Este é um problema comum de migração do Next.js 14, onde os params eram síncronos.

Q: Como valido corpos de requisição com Zod em um route handler?

Analise o corpo com safeParse e verifique parsed.success:

Q: Parâmetros de rota são sempre strings, mesmo que pareçam números?

Sim. Um parâmetro como /api/users/123 retorna id como "123" (string). Analise explicitamente com parseInt(id, 10) ou Number(id) se precisar de um número.

Q: Armadilha: O que acontece se o corpo da requisição não for JSON válido?

request.json() lança um erro em tempo de execução. Sempre envolva-o em um try/catch para robustez em route handlers de produção.

Q: Qual a diferença entre retornar Response e NextResponse?

new Response() funciona, mas carece de helpers específicos do Next.js como cookies() e headers(). NextResponse estende Response com métodos de conveniência. Prefira-o para recursos do Next.js.

Receita

Tipifique os route handlers do App Router do Next.js com NextRequest, NextResponse e parâmetros de rota tipados. Construa endpoints de API type-safe com contratos de requisição/resposta adequados.

Exemplo de Trabalho

// app/api/users/route.ts
import { NextRequest, NextResponse } from "next/server";
 
type User = {
  id: string;
  name: string;
  email: string;
};
 
type CreateUserBody = {
  name: string;
  email: string;
};
 
type ApiErrorResponse = {
  error: string;
};
 
// Handler GET
export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const role = searchParams.get("role");
 
  const users: User[] = await fetchUsersFromDb(role);
 
  return NextResponse.json(users);
}
 
// Handler POST com corpo tipado
export async function POST(request: NextRequest) {
  const body: unknown = await request.json();
 
  if (!isValidCreateUserBody(body)) {
    return NextResponse.json(
      { error: "Corpo da requisição inválido" } satisfies ApiErrorResponse,
      { status: 400 }
    );
  }
 
  const newUser: User = {
    id: crypto.randomUUID(),
    name: body.name,
    email: body.email,
  };
 
  // ... salvar no banco de dados
 
  return NextResponse.json(newUser, { status: 201 });
}
 
// Type guard para o corpo da requisição
function isValidCreateUserBody(body: unknown): body is CreateUserBody {
  return (
    typeof body === "object" &&
    body !== null &&
    "name" in body &&
    "email" in body &&
    typeof (body as CreateUserBody).name === "string" &&
    typeof (body as CreateUserBody).email === "string"
  );
}

// app/api/users/[id]/route.ts - Parâmetros de rota dinâmicos
import { NextRequest, NextResponse } from "next/server";
 
type RouteContext = {
  params: Promise<{ id: string }>;
};
 
export async function GET(request: NextRequest, context: RouteContext) {
  const { id } = await context.params;
 
  const user = await findUserById(id);
 
  if (!user) {
    return NextResponse.json({ error: "Usuário não encontrado" }, { status: 404 });
  }
 
  return NextResponse.json(user);
}
 
export async function DELETE(request: NextRequest, context: RouteContext) {
  const { id } = await context.params;
 
  await deleteUserById(id);
 
  return new NextResponse(null, { status: 204 });
}

Mergulho Profundo

Como Funciona

Route handlers exportam funções nomeadas correspondendo a métodos HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.
NextRequest estende a API Web Request com métodos de conveniência como nextUrl.searchParams para acesso a parâmetros de query.
NextResponse.json(data, init?) cria uma resposta JSON com cabeçalhos Content-Type adequados. O parâmetro data aceita qualquer valor serializável.
No Next.js 15, os params da rota são envolvidos em uma Promise e devem ser aguardados (await). Isso se alinha com o padrão de params assíncronos usado em componentes de página.
Route handlers são código exclusivo do servidor. Eles podem acessar com segurança bancos de dados, variáveis de ambiente e segredos do lado do servidor.

Variações

Validação Zod em route handlers:

import { z } from "zod";
 
const CreateUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
});
 
export async function POST(request: NextRequest) {
  const body = await request.json();
  const parsed = CreateUserSchema.safeParse(body);
 
  if (!parsed.success) {
    return NextResponse.json(
      { error: "Falha na validação", details: parsed.error.flatten() },
      { status: 400 }
    );
  }
 
  const { name, email } = parsed.data; // Totalmente tipado
  // ... criar usuário
}

Configurando cabeçalhos e cookies:

export async function GET(request: NextRequest) {
  const token = request.cookies.get("session")?.value;
 
  if (!token) {
    return NextResponse.json({ error: "Não autorizado" }, { status: 401 });
  }
 
  const response = NextResponse.json({ data: "protegido" });
  response.headers.set("X-Custom-Header", "valor");
  return response;
}

Resposta em streaming:

export async function GET() {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      for (const chunk of ["Olá", " ", "Mundo"]) {
        controller.enqueue(encoder.encode(chunk));
        await new Promise((r) => setTimeout(r, 100));
      }
      controller.close();
    },
  });
 
  return new NextResponse(stream, {
    headers: { "Content-Type": "text/plain" },
  });
}

Notas TypeScript

request.json() retorna Promise<any>. Sempre valide ou converta o resultado antes de usá-lo.
NextResponse.json() aceita qualquer valor. Use satisfies para verificar a forma: NextResponse.json({ error: "msg" } satisfies ApiErrorResponse).
Parâmetros de rota são sempre strings. Mesmo parâmetros que parecem numéricos como /api/users/123 terão id como string. Analise-os explicitamente: parseInt(id, 10).

Armadilhas

No Next.js 15, params é uma Promise. Esquecer de await resulta em um objeto Promise em vez dos params. Este é um problema comum de migração do Next.js 14.
request.json() lança um erro se o corpo não for JSON válido. Envolva-o em um try/catch para robustez.
Route handlers não têm acesso à árvore de componentes React. Eles não podem usar hooks ou context.
Retornar new Response() em vez de NextResponse funciona, mas perde recursos específicos do Next.js como os helpers cookies() e headers().

Alternativas

Abordagem	Prós	Contras
Route Handlers (App Router)	APIs padrão Web, suporte a streaming	Validação manual necessária
Server Actions	Integração mais estreita com formulários React	Não para consumidores de API de terceiros
API Routes (Pages Router)	Padrão `req`/`res` familiar	Legado, `NextApiRequest` é específico do Node
tRPC	Segurança de tipo ponta a ponta	Dependência adicional
API Externa (Express, Fastify)	Controle total, implantação independente	Serviço separado para manter

FAQs

Quais exportações de métodos HTTP um arquivo de route handler suporta?

GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
Exporte cada um como uma função assíncrona nomeada no arquivo route.ts.

Como acesso parâmetros de query em um route handler?

export async function GET(request: NextRequest) {
  const role = request.nextUrl.searchParams.get("role");
  // role é string | null
}

Por que `request.json()` é tipado como `Promise` e o que devo fazer a respeito?

A API Web Request.json() não tem como conhecer a forma do seu payload em tempo de compilação.
Sempre valide ou restrinja o resultado antes de usá-lo (type guard, Zod, ou conversão explícita após verificações).

Como tipar parâmetros de rota dinâmicos no Next.js 15?

type RouteContext = {
  params: Promise<{ id: string }>;
};
 
export async function GET(request: NextRequest, context: RouteContext) {
  const { id } = await context.params;
}

Os parâmetros são envolvidos em uma Promise e devem ser aguardados.

Armadilha: O que acontece se eu esquecer de `await` os params no Next.js 15?

Você recebe um objeto Promise em vez dos params reais.
Este é um problema comum de migração do Next.js 14, onde os params eram síncronos.

Para que serve a palavra-chave `satisfies` em route handlers?

Ela valida que um valor corresponde a um tipo sem alargá-lo:

return NextResponse.json({ error: "msg" } satisfies ApiErrorResponse);

A forma é verificada em tempo de compilação, mas o valor em tempo de execução permanece inalterado.

Como valido corpos de requisição com Zod em um route handler?

Analise o corpo com safeParse e verifique parsed.success:

const parsed = CreateUserSchema.safeParse(await request.json());
if (!parsed.success) {
  return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
}
const { name, email } = parsed.data; // Totalmente tipado

Parâmetros de rota são sempre strings, mesmo que pareçam números?

Sim. Um parâmetro como /api/users/123 retorna id como "123" (string).
Analise explicitamente com parseInt(id, 10) ou Number(id) se precisar de um número.

Armadilha: O que acontece se o corpo da requisição não for JSON válido?

request.json() lança um erro em tempo de execução.
Sempre envolva-o em um try/catch para robustez em route handlers de produção.

Route handlers podem usar hooks React ou acessar a árvore de componentes?

Não. Route handlers são código exclusivo do servidor que roda fora da árvore de componentes React.
Eles não podem usar hooks, context ou qualquer API React do lado do cliente.

Qual a diferença entre retornar `Response` e `NextResponse`?

new Response() funciona, mas carece de helpers específicos do Next.js como cookies() e headers().
NextResponse estende Response com métodos de conveniência. Prefira-o para recursos do Next.js.

Como escrevo um type guard para um corpo de requisição?

function isValidBody(body: unknown): body is CreateUserBody {
  return (
    typeof body === "object" &&
    body !== null &&
    "name" in body &&
    typeof (body as CreateUserBody).name === "string"
  );
}

// app/api/users/route.ts
import { NextRequest, NextResponse } from "next/server";
 
type User = {
  id: string;
  name: string;
  email: string;
};
 
type CreateUserBody = {
  name: string;
  email: string;
};
 
type ApiErrorResponse = {
  error: string;
};
 
// Handler GET
export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const role = searchParams.get("role");
 
  const users: User[] = await fetchUsersFromDb(role);
 
  return NextResponse.json(users);
}
 
// Handler POST com corpo tipado
export async function POST(request: NextRequest) {
  const body: unknown = await request.json();
 
  if (!isValidCreateUserBody(body)) {
    return NextResponse.json(
      { error: "Corpo da requisição inválido" } satisfies ApiErrorResponse,
      { status: 400 }
    );
  }
 
  const newUser: User = {
    id: crypto.randomUUID(),
    name: body.name,
    email: body.email,
  };
 
  // ... salvar no banco de dados
 
  return NextResponse.json(newUser, { status: 201 });
}
 
// Type guard para o corpo da requisição
function isValidCreateUserBody(body: unknown): body is CreateUserBody {
  return (
    typeof body === "object" &&
    body !== null &&
    "name" in body &&
    "email" in body &&
    typeof (body as CreateUserBody).name === "string" &&
    typeof (body as CreateUserBody).email === "string"
  );
}

// app/api/users/[id]/route.ts - Parâmetros de rota dinâmicos
import { NextRequest, NextResponse } from "next/server";
 
type RouteContext = {
  params: Promise<{ id: string }>;
};
 
export async function GET(request: NextRequest, context: RouteContext) {
  const { id } = await context.params;
 
  const user = await findUserById(id);
 
  if (!user) {
    return NextResponse.json({ error: "Usuário não encontrado" }, { status: 404 });
  }
 
  return NextResponse.json(user);
}
 
export async function DELETE(request: NextRequest, context: RouteContext) {
  const { id } = await context.params;
 
  await deleteUserById(id);
 
  return new NextResponse(null, { status: 204 });
}

Mergulho Profundo

Como Funciona

Route handlers exportam funções nomeadas correspondendo a métodos HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.
NextRequest estende a API Web Request com métodos de conveniência como nextUrl.searchParams para acesso a parâmetros de query.
NextResponse.json(data, init?) cria uma resposta JSON com cabeçalhos Content-Type adequados. O parâmetro data aceita qualquer valor serializável.
No Next.js 15, os params da rota são envolvidos em uma Promise e devem ser aguardados (await). Isso se alinha com o padrão de params assíncronos usado em componentes de página.
Route handlers são código exclusivo do servidor. Eles podem acessar com segurança bancos de dados, variáveis de ambiente e segredos do lado do servidor.

Variações

Validação Zod em route handlers:

import { z } from "zod";
 
const CreateUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
});
 
export async function POST(request: NextRequest) {
  const body = await request.json();
  const parsed = CreateUserSchema.safeParse(body);
 
  if (!parsed.success) {
    return NextResponse.json(
      { error: "Falha na validação", details: parsed.error.flatten() },
      { status: 400 }
    );
  }
 
  const { name, email } = parsed.data; // Totalmente tipado
  // ... criar usuário
}

Configurando cabeçalhos e cookies:

export async function GET(request: NextRequest) {
  const token = request.cookies.get("session")?.value;
 
  if (!token) {
    return NextResponse.json({ error: "Não autorizado" }, { status: 401 });
  }
 
  const response = NextResponse.json({ data: "protegido" });
  response.headers.set("X-Custom-Header", "valor");
  return response;
}

Resposta em streaming:

export async function GET() {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      for (const chunk of ["Olá", " ", "Mundo"]) {
        controller.enqueue(encoder.encode(chunk));
        await new Promise((r) => setTimeout(r, 100));
      }
      controller.close();
    },
  });
 
  return new NextResponse(stream, {
    headers: { "Content-Type": "text/plain" },
  });
}

Notas TypeScript

request.json() retorna Promise<any>. Sempre valide ou converta o resultado antes de usá-lo.
NextResponse.json() aceita qualquer valor. Use satisfies para verificar a forma: NextResponse.json({ error: "msg" } satisfies ApiErrorResponse).
Parâmetros de rota são sempre strings. Mesmo parâmetros que parecem numéricos como /api/users/123 terão id como string. Analise-os explicitamente: parseInt(id, 10).

Armadilhas

No Next.js 15, params é uma Promise. Esquecer de await resulta em um objeto Promise em vez dos params. Este é um problema comum de migração do Next.js 14.
request.json() lança um erro se o corpo não for JSON válido. Envolva-o em um try/catch para robustez.
Route handlers não têm acesso à árvore de componentes React. Eles não podem usar hooks ou context.
Retornar new Response() em vez de NextResponse funciona, mas perde recursos específicos do Next.js como os helpers cookies() e headers().

Alternativas

Abordagem	Prós	Contras
Route Handlers (App Router)	APIs padrão Web, suporte a streaming	Validação manual necessária
Server Actions	Integração mais estreita com formulários React	Não para consumidores de API de terceiros
API Routes (Pages Router)	Padrão `req`/`res` familiar	Legado, `NextApiRequest` é específico do Node
tRPC	Segurança de tipo ponta a ponta	Dependência adicional
API Externa (Express, Fastify)	Controle total, implantação independente	Serviço separado para manter

FAQs

Quais exportações de métodos HTTP um arquivo de route handler suporta?

GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
Exporte cada um como uma função assíncrona nomeada no arquivo route.ts.

Como acesso parâmetros de query em um route handler?

export async function GET(request: NextRequest) {
  const role = request.nextUrl.searchParams.get("role");
  // role é string | null
}

Por que `request.json()` é tipado como `Promise` e o que devo fazer a respeito?

A API Web Request.json() não tem como conhecer a forma do seu payload em tempo de compilação.
Sempre valide ou restrinja o resultado antes de usá-lo (type guard, Zod, ou conversão explícita após verificações).

Como tipar parâmetros de rota dinâmicos no Next.js 15?

type RouteContext = {
  params: Promise<{ id: string }>;
};
 
export async function GET(request: NextRequest, context: RouteContext) {
  const { id } = await context.params;
}

Os parâmetros são envolvidos em uma Promise e devem ser aguardados.

Armadilha: O que acontece se eu esquecer de `await` os params no Next.js 15?

Você recebe um objeto Promise em vez dos params reais.
Este é um problema comum de migração do Next.js 14, onde os params eram síncronos.

Para que serve a palavra-chave `satisfies` em route handlers?

Ela valida que um valor corresponde a um tipo sem alargá-lo:

return NextResponse.json({ error: "msg" } satisfies ApiErrorResponse);

A forma é verificada em tempo de compilação, mas o valor em tempo de execução permanece inalterado.

Como valido corpos de requisição com Zod em um route handler?

Analise o corpo com safeParse e verifique parsed.success:

const parsed = CreateUserSchema.safeParse(await request.json());
if (!parsed.success) {
  return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
}
const { name, email } = parsed.data; // Totalmente tipado

Parâmetros de rota são sempre strings, mesmo que pareçam números?

Sim. Um parâmetro como /api/users/123 retorna id como "123" (string).
Analise explicitamente com parseInt(id, 10) ou Number(id) se precisar de um número.

Armadilha: O que acontece se o corpo da requisição não for JSON válido?

request.json() lança um erro em tempo de execução.
Sempre envolva-o em um try/catch para robustez em route handlers de produção.

Route handlers podem usar hooks React ou acessar a árvore de componentes?

Não. Route handlers são código exclusivo do servidor que roda fora da árvore de componentes React.
Eles não podem usar hooks, context ou qualquer API React do lado do cliente.

Qual a diferença entre retornar `Response` e `NextResponse`?

new Response() funciona, mas carece de helpers específicos do Next.js como cookies() e headers().
NextResponse estende Response com métodos de conveniência. Prefira-o para recursos do Next.js.

Como escrevo um type guard para um corpo de requisição?

function isValidBody(body: unknown): body is CreateUserBody {
  return (
    typeof body === "object" &&
    body !== null &&
    "name" in body &&
    typeof (body as CreateUserBody).name === "string"
  );
}

Tipagem de Route Handlers

Receita

Exemplo de Trabalho

Mergulho Profundo

Como Funciona

Variações

Notas TypeScript

Armadilhas

Alternativas

FAQs

Relacionados

Tipagem de Route Handlers

Receita

Exemplo de Trabalho

Mergulho Profundo

Como Funciona

Variações

Notas TypeScript

Armadilhas

Alternativas

FAQs

Relacionados

Tipagem de Route Handlers

Buscar na documentação

Tipagem de Route Handlers