jsschools

Route Handlers

Build API endpoints with Web Request/Response in route.js files.

Since Next 13.2 (App Router) Spec ↗

Syntax

export async function GET/POST/...(request, context) { return Response }

Parameters

NameTypeRequiredDescription
request Request | NextRequest No The incoming Web request.
context { params: Promise<...> } No Route context with async params (Next 15).

Returns

Response | Promise<Response> — Standard Web Response.

Examples

// app/api/search/route.ts
import { NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  const q = request.nextUrl.searchParams.get('q') ?? ''
  const results = await search(q)
  return Response.json({ results })
}

// app/api/upload/route.ts
export async function POST(request: Request) {
  const form = await request.formData()
  const file = form.get('file') as File
  const url = await store(file)
  return Response.json({ url }, { status: 201 })
}

// Streaming response
export async function GET() {
  const stream = new ReadableStream({
    start(controller) {
      controller.enqueue('hello')
      controller.close()
    },
  })
  return new Response(stream)
}

Notes

Live in `app/.../route.js` and export HTTP-method functions. Use the Web `Request`/`Response` (or `NextResponse`). GET handlers are not cached by default in Next 15; opt in via segment config. Cannot coexist with `page.js` in the same segment. Validate and authorize requests.

See also