Route Handlers

Route Handlers allow you to create custom request handlers for a given route using the Web Request and Response APIs.
Route Handlers are only available inside the app directory. They are the equivalent of API Routes inside the pages directory meaning you do not need to use API Routes and Route Handlers together.
Route Handlers are defined in a route.js|ts file inside the app directory:
Route Handlers can be nested anywhere inside the app directory, similar to page.js and layout.js. But there cannot be a route.js file at the same route segment level as page.js.
The following HTTP methods are supported: GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS. If an unsupported method is called, Next.js will return a 405 Method Not Allowed response.
In addition to supporting the native Request and Response APIs, Next.js extends them with NextRequest and NextResponse to provide convenient helpers for advanced use cases.
Route Handlers are not cached by default. You can, however, opt into caching for GET methods. Other supported HTTP methods are not cached. To cache a GET method, use a route config option such as export const dynamic = 'force-static' in your Route Handler file.
Other supported HTTP methods are not cached, even if they are placed alongside a GET method that is cached, in the same file.
When Cache Components is enabled, GET Route Handlers follow the same model as normal UI routes in your application. They run at request time by default, can be prerendered when they don't access uncached or runtime data, and you can use use cache to include uncached data in the static response.
Static example - doesn't access uncached or runtime data, so it will be prerendered at build time:
Dynamic example - accesses non-deterministic operations. During the build, prerendering stops when Math.random() is called, deferring to request-time rendering:
Runtime data example - accesses request-specific data. Prerendering terminates when runtime APIs like headers() are called:
Prerendering stops if the GET handler accesses network requests, database queries, async file system operations, request object properties (like req.url, request.headers, request.cookies, request.body), runtime APIs like cookies(), headers(), connection(), or non-deterministic operations.
Cached example - accesses uncached data (database query) but caches it with use cache, allowing it to be included in the prerendered response:
use cache cannot be used directly inside a Route Handler body; extract it to a helper function. Cached responses revalidate according to cacheLife when a new request arrives.
Special Route Handlers like sitemap.ts, opengraph-image.tsx, and icon.tsx, and other metadata files remain static by default unless they use Request-time APIs or dynamic config options.
You can consider a route the lowest level routing primitive.
Each route.js or page.js file takes over all HTTP verbs for that route.
Read more about how Route Handlers complement your frontend application, or explore the Route Handlers API Reference.
In TypeScript, you can type the context parameter for Route Handlers with the globally available RouteContext helper:
Learn more about Route Handlers
Last updated August 27, 2026
Subscribe to our newsletter
Stay updated on new releases and features, guides, and case studies.