Backend-for-frontend endpoints
Create JSON endpoints for browser, mobile, or server clients.
Next.js 16+ · Directive
route
Route Handlers define custom HTTP endpoints in the App Router with route.ts or route.js files. Export functions named for supported HTTP methods and return standard web Response objects.
- Since
- 13.2
How it works
A route.ts or route.js file defines HTTP handlers for a URL inside the app directory. Export functions named for supported HTTP methods; each receives the web Request and returns a web Response, letting the endpoint implement server-side behavior without a page component.
Syntax
export async function GET(request: Request): Promise<Response> {}Parameters
| Name | Type | Description |
|---|---|---|
request | Request | The incoming web request, including URL, headers, and body. |
Returns
A web Response object.
Key points
- Use a route.ts or route.js file to implement a custom server endpoint for its route segment.
- Handlers use standard web Request input and Response output types.
- The special filename is route.js or route.ts.
- Directory nesting determines where the endpoint lives in the App Router.
- A route file provides the most direct routing primitive in the App Router.
Common mistakes
- Place the file under app; a route handler is not supported in the pages directory.
- Do not colocate route.ts with page.tsx in the same segment.
- Choose Route Handlers or Pages Router API Routes rather than combining both for the same application needs.
Example: A GET Route Handler
export async function GET(request: Request) {
const name = new URL(request.url).searchParams.get("name") ?? "world"
return Response.json({ message: `Hello, ${name}!` })
}Save this as app/api/hello/route.ts, then request /api/hello?name=Next.js.
When to use it
Mutation handlers
Receive data from forms or other clients through POST requests.
Custom HTTP behavior
Expose server-side logic at a URL without rendering a page.
Interview questions
QWhat is a Route Handler in Next.js?
A Route Handler is a custom request handler defined by a route.js or route.ts file in the app directory. It uses the web Request and Response APIs and is the App Router counterpart to an API Route.
Follow-up: Where can a handler be placed? It can be nested anywhere in app, provided it does not share the same route segment as page.js.
QHow do you define HTTP methods?
Export an async function whose name is an HTTP method, such as GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS. The function can inspect the Request and return a Response.
Follow-up: How would you support multiple verbs? Export one appropriately named handler for each method the endpoint needs.
QHow does a route file map to an endpoint?
Route Handlers are the lowest-level routing primitive and can be nested in the app directory similarly to page.js and layout.js. Their URL comes from the directory structure containing the route file.
Follow-up: What replaces a Pages Router API endpoint in the App Router? A route.js or route.ts Route Handler under app.
Related
RouteContextNextResponsepage.jslayout.jsAPI Routes