Code Reference

Route Handlers

Next.js · Reference cheat sheet

Route Handlers

Next.js · Reference cheat sheet

📋 Overview

Route Handlers live in app/**/route.ts (or .js) and export HTTP method functions. They replace many pages/api use cases in the App Router.

🔧 Core concepts

ExportHTTP method
GETRead
POSTCreate / submit
PUT / PATCHUpdate
DELETEDelete
HEAD / OPTIONSMeta / CORS
HelperUse
NextRequestExtended Request (cookies, nextUrl)
NextResponseJSON, redirects, cookies
paramsDynamic segment values

💡 Examples

JSON GET:

// app/api/hello/route.ts
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "hi" });
}

POST with body:

import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const body = await req.json();
  return NextResponse.json({ received: body }, { status: 201 });
}

Dynamic segment:

// app/api/users/[id]/route.ts
export async function GET(
  _req: Request,
  ctx: { params: Promise<{ id: string }> },
) {
  const { id } = await ctx.params;
  return Response.json({ id });
}

⚠️ Pitfalls

  • Don't export a page.tsx and route.ts for the same path segment.
  • Default caching of GET can surprise you — set export const dynamic = 'force-dynamic' when needed.
  • Large file uploads need streaming/FormData care; don't assume unlimited body size.

🔗 Related

Pages Router

Next.js · Reference cheat sheet

Server Components

Next.js · Reference cheat sheet

On this page

Route Handlers📋 Overview🔧 Core concepts💡 Examples⚠️ Pitfalls🔗 Related