Nested Routing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The nested routing strategy in wouter-vue allows developers to define hierarchical route structures where parent routes can contain and manage child routes. This strategy is built on the project's minimalist philosophy, leveraging Vue 3's Composition API and the path-to-regexp library to handle complex path matching and reactive data flow across different levels of the component tree.
By utilizing the nest property on a Route component, the router can loosely match a pattern, allowing subsequent child routes to resolve paths relative to the parent's matched segment. This architecture supports deep nesting while maintaining a small bundle size and high performance.
Sources: README.md:14-38, test/nested-route.test.ts:7-25
Core Nesting Mechanics
The primary mechanism for nesting is the nest prop on the <Route /> component. When enabled, the route matches the current location loosely (i.e., it matches if the path starts with the specified pattern), effectively acting as a prefix for any routes defined within its slot.
Loose Pattern Matching
Unlike standard routes that require an exact match, a nested route validates if the current URL begins with its defined path. This allows a parent route to remain mounted while the browser navigates through sub-paths handled by internal components.
Sources: test/nested-route.test.ts:27-50
This diagram illustrates how a single URL is processed through a hierarchy of routes where the parent consumes a segment and passes the remainder to the child.
Sources: test/nested-route.test.ts:71-84
Hierarchical Data Passing
A significant feature of the nesting strategy is the ability to pass reactive data down the routing tree. This is achieved through automatic merging of data objects provided at different levels.
Data Flow and Merging
Data can be passed via the data prop on components like AnimatedSwitch or Route. Components deep in the hierarchy can access this aggregated data using the useRouteData() composable or via props.
Sources: README.md:38-38, examples/example/src/pages/AboutPage.vue:10-30
| Feature | Description | Implementation |
|---|---|---|
| Reactive Merging | Parent and child data objects are merged automatically. | useRouteData() |
| Prop Injection | Route parameters and data are injected as props into the :component. | defineProps(['data', 'params']) |
| Scoped Access | Components can selectively access data from their specific branch. | Composition API |
Sources: examples/example/src/pages/AboutPage.vue:71-92, README.md:43-43
Path Resolution and Links
Navigation within nested structures requires a specific strategy for path resolution to ensure links point to the correct locations regardless of the current nesting depth.
Relative vs. Absolute Links
Wouter-vue supports a ~ prefix for links within nested routes. This allows developers to define links relative to the application root even when deep within a nested routing context.
- Standard Link: Resolves based on the current routing context or as an absolute path if it starts with
/. - Root-Relative Link (
~): Explicitly ignores the current nested base and resolves from the root.
Sources: test/nested-route.test.ts:86-103
Multiple Levels of Nesting
The architecture supports arbitrary nesting depths. Each nested route creates a new routing context with a refreshed base path for its children.
Sources: test/nested-route.test.ts:106-130
The sequence diagram demonstrates the recursive matching process used to resolve deeply nested components.
Sources: test/nested-route.test.ts:107-124
Parameter Propagation
Parameters extracted from the URL (e.g., :userId) are automatically propagated from parent routes to their children. This ensures that a child component has access to the context established by its parents.
Sources: test/nested-route.test.ts:132-152
// Example of accessing parent params in a nested child
const props = defineProps({
params: Object // Contains { userId: '999' } from parent /users/:userId
});
Sources: test/nested-route.test.ts:145-148, examples/example/src/pages/AboutPage.vue:76-87
Build-Time Optimization
For large-scale nested applications, the vite-plugin-routes can be used to generate static routes. This avoids the overhead of dynamic imports at runtime while maintaining the ability to split code based on route branches.
Route Compression
The plugin can detect numeric or patterned route structures and compress them into a more compact format, reducing the initial bundle size of the routing configuration.
Sources: src/vite-plugin-routes.ts:133-170
Manual Chunking
The plugin facilitates grouping related route components into named chunks. This is particularly useful for nested routes where all components within a specific sub-feature can be grouped into a single network request.
Sources: src/vite-plugin-routes.ts:219-250
Summary
The nested routing strategy in wouter-vue provides a powerful yet lightweight way to manage hierarchical views. By combining loose pattern matching (nest prop) with reactive data merging and smart path resolution, it allows for complex UI structures without the performance penalties typically associated with heavy routing libraries. The inclusion of Vite-native optimization tools further ensures that even deeply nested applications remain fast and maintainable.
Sources: README.md:46-60, examples/example/README.md:7-15