Routing Information

Core Idea

Reference for the routing object passed to onBuildComplete, describing Next.js's routing phases and the common shape of each route rule.

Key Concepts

• routing.beforeMiddleware: routes applied before middleware execution (generated header/redirect behavior).
• routing.beforeFiles: rewrite routes checked before filesystem route matching.
• routing.afterFiles: rewrite routes checked after filesystem route matching.
• routing.dynamicRoutes: dynamic matchers generated from segments like [slug] and catch-all routes.
• routing.onMatch: routes applied after a successful match (e.g. immutable cache headers for hashed static assets).
• routing.fallback: final rewrite routes checked when earlier phases produced no match.

Reference Tables

Route field	Meaning
source	Original route pattern (optional for internal generated rules)
sourceRegex	Compiled regex for matching requests
destination	Internal destination or redirect destination
headers	Headers to apply
has	Positive matching conditions
missing	Negative matching conditions
status	Redirect status code
priority	Internal route priority flag

Key Takeaways

1. The five routing phases (beforeMiddleware → beforeFiles → afterFiles → dynamicRoutes/onMatch → fallback) mirror the order Next.js itself evaluates a request.
2. onMatch is specifically where post-match behaviors like immutable asset cache headers get attached.
3. Every route entry shares one common field shape, making it possible to write a single matcher/serializer across all phases.

Connects To

• ch275 routing-with-next-routing: @next/routing's resolveRoutes() consumes this exact routing object as its routes argument.
• ch273 api-reference-1: where context.routing first appears in the onBuildComplete signature.