Introduction to wouter-vue
Relevant source files
The following files were used as context for generating this wiki page:
wouter-vue is a minimalist, high-performance routing library for Vue 3, heavily inspired by the design philosophy of the original React wouter. It prioritizes a tiny bundle size—approximately 7.9KB gzipped—and leverages the Vue 3 Composition API to provide a reactive, hook-based routing experience without the overhead of traditional heavy routers.
The library is designed to be "minimalist-friendly," meaning it does not require a mandatory top-level provider to function, although it provides an optional <Router /> component for advanced configurations. It utilizes path-to-regexp for robust, industry-standard route matching and supports modern features like Server-Side Rendering (SSR) and hierarchical data passing.
Sources: README.md:14-27, package.json:2-10
Core Components and Usage
The library provides a set of declarative components that manage the routing logic and UI state within a Vue application.
Key Components
| Component | Description |
|---|---|
<Router /> | Optional top-level component to provide routing context; not strictly required for basic usage. |
<Route /> | Matches the current location against a specified path and renders its children or a dedicated component. |
<Link /> | A replacement for the standard anchor tag that performs navigation without full page reloads. |
Sources: README.md:38-46, README.md:120-135
Route Matching Logic
The following diagram illustrates how the <Route /> component interacts with the browser's location to determine visibility.
The router uses path-to-regexp to extract dynamic parameters from the URL, which are then accessible via composables.
Sources: README.md:43-45, examples/example/src/pages/UserDetailPage.vue:43-50
Composition API (Composables)
wouter-vue is "Composition API first," offering several reactive functions to interact with the routing state programmatically.
useLocation
Used for reading the current path and performing programmatic navigation. It returns an array where the first element is the reactive location and the second is a function to navigate.
Sources: examples/example/README.md:104-109
useParams
Extracts dynamic segments from the current route (e.g., :id).
Sources: examples/example/src/pages/UserDetailPage.vue:43-45, examples/example/README.md:89-94
useRouteData and useSearchParams
useRouteData: Retrieves reactive data passed down from parent routing trees.useSearchParams: Provides access to URL query parameters in a reactive format.
Sources: examples/example/src/pages/AboutPage.vue:81-90
Performance and Architecture
The library is optimized for high-throughput applications, demonstrating significant advantages over standard routing solutions in benchmarks.
Comparison Metrics
Based on load testing with 3,300 virtual users and 200 routes:
| Metric | wouter-vue | vue-router | Advantage |
|---|---|---|---|
| Throughput | 117 req/s | 68 req/s | +72% faster |
| Total Requests | 36,300 | 19,800 | +83% more |
| Median Latency | 1 ms | 1 ms | Identical |
Sources: README.md:52-68
Navigation Flow
The sequence below shows how a user interaction triggers a route change and component update.
Advanced Features
Server-Side Rendering (SSR)
wouter-vue includes built-in support for SSR, allowing developers to handle routing on the server using Vite. This is facilitated through specialized location hooks designed for non-browser environments.
Sources: README.md:48, package.json:67-70
Async Components and Code Splitting
The library integrates seamlessly with Vue's <Suspense> and defineAsyncComponent to support lazy loading of routes.
<Suspense>
<Route path="/heavy" :component="HeavyPageAsync" />
<template #fallback>
<LoadingSpinner />
</template>
</Suspense>
Sources: examples/example/README.md:73-87
Active Link Styling
The <Link /> component supports a scoped slot or functional class API to apply styles when the link's href matches the current location.
Sources: examples/example/README.md:96-102, examples/example/src/pages/HomePage.vue:1-35
Summary
wouter-vue provides a high-performance, developer-friendly alternative to heavier Vue routers. By focusing on the Composition API and a minimal footprint (~7.9KB), it serves as an efficient solution for projects where bundle size and request throughput are critical, while still maintaining compatibility with advanced patterns like SSR and nested routing.
Sources: README.md:14-25, README.md:65-70