Path Matching Logic
Relevant source files
The following files were used as context for generating this wiki page:
Path matching in wouter-vue is a high-performance routing mechanism that uses industry-standard patterns to map browser URLs to specific Vue 3 components. The logic is primarily powered by the path-to-regexp library, which provides robust support for dynamic parameters, nested structures, and wildcards. Sources: README.md:37-41, package.json:134
The system is designed to be "Composition API first," leveraging Vue's reactivity system to track location changes and update the UI accordingly. It supports both static path matching and dynamic parameter extraction, ensuring compatibility with standard routing patterns while maintaining a minimal bundle size. Sources: README.md:21-30, examples/example/README.md:46-52
Path Normalization and Resolution
Before a path is compared against a route pattern, it undergoes normalization to ensure consistency. This process involves stripping auxiliary URL components that do not affect the route selection.
Normalization Process
The normalizePath utility handles the following transformations:
- Query String Removal: Everything following the
?character is discarded. - Hash Removal: Everything following the
#character is discarded. - Trailing Slash Handling: Trailing slashes are removed from all paths except the root
/. Empty strings are normalized to/.
Sources: src/helpers/path-helpers.ts:13-29
Target Path Resolution
When navigating via the <Link> component, the router must resolve the target destination from either the href or to props. The resolveTargetPath function manages this priority, typically defaulting to one based on the preferTo configuration. Sources: src/helpers/path-helpers.ts:38-46
The following flow illustrates the normalization of a raw URL before matching:
Sources: src/helpers/path-helpers.ts:13-29
Route Pattern Matching
The core matching logic relies on path-to-regexp to convert path strings into regular expressions. This allows for sophisticated matching including named parameters and wildcards.
Key Pattern Types
| Pattern Type | Example | Description |
|---|---|---|
| Static | /about | Matches exact paths. |
| Dynamic Param | /users/:id | Captures segments into a parameters object. |
| Wildcard | /* | Used for catch-all/404 handling. |
| Nested | /parent/child | Supported via hierarchical structures. |
Sources: README.md:52-54, examples/example/README.md:32-38
Parameter Extraction
When a match is successful, dynamic segments (defined with a colon prefix like :id) are extracted and made available to components via the useParams hook or as props. Sources: examples/example/README.md:65-71, examples/example/src/pages/AboutPage.vue:56-65
Build-Time Route Generation
For performance optimization, especially in large-scale applications, the project includes a Vite plugin (vite-plugin-routes) that can generate static routes at build time. This avoids the overhead of dynamic imports during the initial path-matching phase.
Plugin Logic
The plugin scans a specified directory for Vue components matching a regex pattern (e.g., Route(\d+).vue). It generates a routes configuration file that maps these files to URL paths. Sources: src/vite-plugin-routes.ts:11-30
Optimization Features
- Compression: If routes follow a numeric pattern (like
/route1,/route2), the plugin generates a compressed array to reduce bundle size. - Manual Chunks: It automatically groups generated routes into specific Rollup chunks to optimize loading performance.
Sources: src/vite-plugin-routes.ts:141-175, src/vite-plugin-routes.ts:228-255
Summary
The path matching logic in wouter-vue combines strict normalization utilities with the flexibility of path-to-regexp. By providing tools for both runtime matching (via Composition API hooks) and build-time optimization (via Vite plugins), the system ensures high throughput and minimal latency. Key metrics show the router can handle up to 72% higher throughput compared to standard solutions like vue-router while maintaining identical median latency. Sources: README.md:60-75, src/helpers/path-helpers.ts:13-29