Migration from vue-router
Relevant source files
The following files were used as context for generating this wiki page:
Wouter-vue is a minimalist, high-performance alternative to vue-router for Vue 3 applications. It focuses on the Composition API and a smaller footprint (~7.9KB gzipped), providing a 72% higher throughput and handling 83% more requests compared to vue-router. This guide outlines the architectural differences and component mapping required to transition an application from vue-router to wouter-vue.
Sources: README.md:1-55, examples/example/README.md:1-10
Component Mapping
The migration primarily involves replacing vue-router global components with wouter-vue alternatives. While vue-router relies on a centralized router instance and <router-view>, wouter-vue uses a declarative, component-based approach.
| vue-router Component | wouter-vue Component | Key Differences |
|---|---|---|
<router-link> | <Link> | Link uses href instead of to and provides a scoped slot for active states. |
<router-view> | <Route> / <Router> | Route defines the path and component directly; Router is optional and provides context. |
| N/A | <AnimatedSwitch> | Handles transitions and hierarchical data passing between routes. |
Sources: README.md:105-121, examples/example-vue-router/src/pages/HomePage.vue:24-27, examples/example/src/pages/HomePage.vue:24-27, examples/example/src/components/AppRoutes.vue:4-10
Link Component Conversion
In vue-router, navigation is handled by <router-link to="/path">. In wouter-vue, this is replaced by the <Link> component using the href attribute.
<!-- vue-router -->
<router-link to="/about">About Page</router-link>
<!-- wouter-vue -->
<Link href="/about">About Page</Link>
Sources: examples/example-vue-router/src/pages/HomePage.vue:24, examples/example/src/pages/HomePage.vue:24
Composition API and Composables
Wouter-vue provides a set of hooks (composables) that mirror the functionality of vue-router but are optimized for the minimalist architecture of the library.
Navigation and Location
vue-router uses useRouter for programmatic navigation and useRoute for current route information. wouter-vue provides useLocation which returns a tuple containing the current path and a navigation function.
The diagram shows the functional equivalence between vue-router hooks and the wouter-vue useLocation composable.
Sources: examples/example-vue-router/src/pages/AboutPage.vue:43-45, examples/example/src/pages/AboutPage.vue:75-76, examples/example/README.md:67-71
Parameter Handling
While vue-router provides parameters via route.params, wouter-vue uses the useParams composable or passes parameters directly as props to components defined in a <Route>.
| Feature | vue-router | wouter-vue |
|---|---|---|
| Path Params | useRoute().params | useParams() or props.params |
| Search/Query | useRoute().query | useSearchParams() |
| Active State | Automatic | :class="isActive => ..." |
Sources: examples/example-vue-router/src/pages/AboutPage.vue:43-45, examples/example/src/pages/AboutPage.vue:75-78, examples/example/README.md:52-56
Hierarchical Data and Transitions
A significant feature of wouter-vue that differs from vue-router is the built-in support for hierarchical and reactive data passing. The <AnimatedSwitch> and <Route> components allow passing a :data prop which is merged down the routing tree.
The sequence diagram illustrates how reactive data is merged and injected into components during navigation.
Sources: examples/example/src/components/AppRoutes.vue:4-15, examples/example/src/pages/AboutPage.vue:75-81, README.md:46-47
Implementation of Route Data
Components can access this data using the useRouteData composable.
// AboutPage.vue
import { useRouteData } from 'wouter-vue';
const routeData = useRouteData();
console.log(routeData.value.theme); // 'dark'
Sources: examples/example/src/pages/AboutPage.vue:81, examples/example/src/components/AppRoutes.vue:20-24
Route Configuration
Unlike vue-router, which typically uses a static array of route objects passed to createRouter, wouter-vue uses a declarative template-based configuration. This is often wrapped in a <Suspense> block to handle async components.
<!-- wouter-vue declarative routing -->
<template>
<Suspense>
<AnimatedSwitch>
<Route path="/" :component="HomePage" />
<Route path="/about" :component="AboutPage" />
<Route path="/users/:id" :component="UserDetailPage" />
</AnimatedSwitch>
<template #fallback><LoadingSpinner /></template>
</Suspense>
</template>
Sources: examples/example/src/components/AppRoutes.vue:3-17, examples/example/README.md:40-50
Performance Benefits
Transitioning to wouter-vue is primarily motivated by performance in high-traffic scenarios.
| Metric | Advantage |
|---|---|
| Throughput | +72% faster (117 vs 68 req/s) |
| Total Requests | +83% more requests (36,300 vs 19,800) |
| Bundle Size | ~7.9KB gzipped (72% smaller) |
Sources: README.md:57-75
Conclusion
Migrating from vue-router to wouter-vue involves shifting from a centralized router configuration to a component-based declarative structure. By replacing router-link with Link and adopting the useLocation and useParams composables, developers can significantly reduce bundle size and improve application throughput while maintaining support for advanced features like SSR and nested routing.