Routing & Pages Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Routing & Pages Engine is a core Nuxt module responsible for the automatic generation of application routes based on the file system structure. It orchestrates the scanning of page directories, extracts metadata from Vue components, and compiles a comprehensive route tree utilized by both the server and the client. The engine bridges the gap between directory-based file organization and vue-router configurations, providing a type-safe and performant navigation system.
Sources: packages/nuxt/src/pages/module.ts:37-65, packages/schema/src/types/schema.ts:50-60
Core Architecture and Lifecycle
The engine operates within the Nuxt build lifecycle, specifically hooking into the app:resolve and builder:watch stages. In development mode, it maintains a persistent PagesContext that allows for incremental updates to the route tree as files are added or removed, avoiding costly full rebuilds.
The following diagram illustrates the high-level flow of route generation:
The diagram shows the sequential process from physical file scanning to the generation of the final router configuration.
Sources: packages/nuxt/src/pages/module.ts:65-95, packages/nuxt/src/pages/module.ts:300-335
Route Resolution and Normalization
The engine converts physical file paths into NuxtPage objects. This process includes handling complex patterns like dynamic segments (e.g., [id].vue), catch-all routes ([...slug].vue), and optional parameters ([[optional]].vue).
| Component Type | File Pattern | Generated Route Path |
|---|---|---|
| Static Page | index.vue | / |
| Dynamic Segment | [slug].vue | /:slug() |
| Optional Param | [[foo]].vue | /:foo? |
| Catch-all | [...slug].vue | /:slug(.*)* |
| Group Route | (group)/index.vue | / |
Sources: packages/nuxt/test/pages.test.ts:300-450, packages/nuxt/src/pages/module.ts:40-45
Metadata Extraction and Macros
Nuxt utilizes compiler macros like definePageMeta to allow developers to declare route-specific behavior directly within the <script setup> block. The engine extracts this data at build time to populate the RouteMeta in the final router configuration.
definePageMeta
This macro supports properties such as middleware, layout, alias, and redirect. When experimental.scanPageMeta is enabled, the engine extracts serializable values into the generated route record, reducing the need to import the full macro module during dev-mode navigation.
export interface PageMeta {
validate?: (route: RouteLocationNormalized) => boolean | Partial<NuxtError> | Promise<boolean>
redirect?: RouteRecordRedirectOption
alias?: string | string[]
layout?: MaybeRef<LayoutKey | false>
middleware?: MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>
scrollToTop?: boolean | ((to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded) => boolean)
}
Sources: packages/nuxt/src/pages/runtime/composables.ts:18-50, packages/nuxt/src/pages/module.ts:510-530
Route Rules and Nitro Integration
Route rules provide a way to configure server-side behaviors (like ISR, SWR, or redirects) based on the route path. The engine can glob these rules directly from the rules property within definePageMeta when experimental.inlineRouteRules is enabled.
This diagram demonstrates how page-level metadata is translated into Nitro server configuration.
Sources: packages/nuxt/src/pages/module.ts:75-85, packages/nuxt/src/pages/route-rules.ts:1-50
Experimental and Advanced Features
The Routing Engine includes several advanced mechanisms to improve developer experience and performance:
- Typed Pages: When
experimental.typedPagesis enabled, the engine generates atyped-router.d.tsdeclaration file usingvue-router/unplugin. This provides strict type-checking for route names and parameters throughout the application. - Component Islands: The engine detects server-only components (
.server.vue) and automatically registers them as islands when no client equivalent exists, allowing for server-side-only rendering within a client-side navigation context. - Named Views: Supports the
name@view.vuefilename convention to emit multiple named components for a single route.
Sources: packages/nuxt/src/pages/module.ts:200-260, packages/nuxt/src/components/templates.ts:90-120, packages/nuxt/test/pages.test.ts:180-200
Diagnostics and Validation
The engine includes a robust diagnostic system to prevent common routing errors. These are handled via the nostics library.
| Error Code | Meaning | Resolution |
|---|---|---|
| NUXT_B4001 | Empty page file | Add <template> or remove the file. |
| NUXT_B4003 | Multiple definePageMeta calls | Merge into a single call. |
| NUXT_B4004 | Route name collision | Set a custom name in definePageMeta. |
| NUXT_B4008 | SSR False with Islands | Ensure experimental.componentIslands is true. |
| NUXT_B4015 | Public asset conflict | Rename the asset or the conflicting page. |
Sources: packages/kit/src/diagnostics/pages.ts:10-85
Conclusion
The Routing & Pages Engine is a sophisticated subsystem that transforms a declarative file-based structure into a dynamic, type-safe routing layer. By integrating tightly with Nitro for server-side rules and utilizing build-time macro extraction, it ensures that Nuxt applications remain performant and easy to manage as they scale.