Next.js Route Segment Config

WHY IT EXISTS A modern app isn't monolithic. Some parts need low latency, while others need powerful compute or long execution times. Route Segment Config exists to move this configuration from a single global file into the routes themselves, allowing each part of your app to have the specific environment it needs to perform best.

THE MENTAL MODEL Imagine your Next.js app is a building with many rooms (routes). Instead of a single central thermostat (next.config.js) for the whole building, Route Segment Config gives each room its own thermostat and light switch. You can make one room a cold, fast serverless function on the edge, and another a warm, long-running Node.js server for heavy tasks, all within the same application.

HOW IT WORKS You export special constant variables from a page.js, route.js, or layout.js file. Next.js reads these variables at build time and configures the deployment for that specific route segment. The key options are runtime, preferredRegion, maxDuration, and dynamicParams. For example, exporting export const runtime = 'edge'; in app/api/fast/route.js tells the deployment platform to run this specific API route on its edge network.

WHEN TO USE IT Use it when you have mixed requirements in your app. A classic case is an e-commerce site: run product pages and APIs on the edge for speed (runtime = 'edge'), but run the checkout processing or report generation on the Node.js runtime (runtime = 'nodejs') where you might need more time (maxDuration) or specific Node libraries. It's also used to control how dynamic routes behave with dynamicParams.

WHEN NOT TO USE IT Don't use it if your entire application has uniform requirements. If every page can run on the same runtime with the same timeout, setting these globally in next.config.js is simpler. Overusing per-route configs can make the application's behavior harder to reason about if not documented well. It's for exceptions, not the rule.

ONE CANONICAL EXAMPLE To handle a long-running data export API route without timing out, you can create a file app/api/export/route.js and add this configuration. This tells Next.js to use the Node.js runtime and allows the function to run for up to 300 seconds, far beyond the typical default for serverless functions. export const runtime = 'nodejs'; export const maxDuration = 300; export async function GET(request) { /* ... long-running logic ... */ }