Getting Started & Installation

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• examples/example/README.md
• examples/example/package.json
• src/vite-plugin-routes.ts
• examples/README.md

wouter-vue is a minimalist, high-performance routing library for Vue 3, heavily inspired by the React router wouter. It is designed to be tiny (~2KB gzipped for the core logic) and leverages the Vue 3 Composition API to provide a reactive routing experience without the overhead of traditional routing solutions. The project emphasizes a "Composition API first" approach, offering optional top-level components and industry-standard pattern matching via path-to-regexp.

Sources: README.md:1-25, package.json:2-10

Installation

To integrate wouter-vue into your project, you must ensure your environment meets the minimum requirement of Vue version 3.5.22 or higher.

Sources: README.md:85-90, package.json:115-117

Package Manager Commands

You can install the package using any of the major JavaScript package managers:

# npm
npm install wouter-vue

# pnpm
pnpm add wouter-vue

# yarn
yarn add wouter-vue

Sources: README.md:77-83

Core Architecture & Components

The library provides three primary building blocks for routing: Router, Route, and Link. Unlike many other routers, the <Router /> component is optional, allowing for more flexible architectural patterns.

The diagram shows how components interact with the matching engine and browser history.
Sources: README.md:27-40, README.md:92-108

Key Components

Component	Description	Essential Props
<Router />	Optional provider component that manages routing state and configuration.	base, hook
<Route />	Defines a mapping between a URL pattern and a component or slot.	path, component
<Link />	A wrapper for <a> tags that prevents page refreshes and handles internal navigation.	href or to

Sources: README.md:92-108, examples/example/README.md:22-68

Quick Start Configuration

A basic setup involves importing the core components and defining your route structure within a template.

<template>
  <Router>
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
    </nav>
    
    <Route path="/" component={HomePage} />
    <Route path="/about">
      <AboutPage />
    </Route>
  </Router>
</template>

<script setup>
import { Router, Route, Link } from 'wouter-vue';
import HomePage from './pages/HomePage.vue';
import AboutPage from './pages/AboutPage.vue';
</script>

Sources: README.md:92-110

Advanced Setup: Vite Plugin

For large-scale applications with hundreds of routes, wouter-vue provides a Vite plugin to generate static routes at build time. This avoids excessive dynamic imports and optimizes bundle size.

The sequence diagram illustrates the automated route generation process during the Vite build cycle.
Sources: src/vite-plugin-routes.ts:108-140, src/vite-plugin-routes.ts:180-210

Vite Plugin Configuration

The plugin can be configured in vite.config.ts to customize how routes are discovered and generated.

Option	Type	Default	Description
dir	string	'src/pages/routes'	Directory containing route files.
pattern	RegExp	/Route(\d+)\.vue$/	Regex to identify valid route components.
outputFile	string	'src/generated-routes.js'	Path for the generated route manifest.
compress	boolean	true	Uses templates to reduce generated file size.

Sources: src/vite-plugin-routes.ts:14-63

Project Structure (Example)

When starting with a standard project structure as seen in the provided examples, the following layout is recommended:

• src/main.js: Entry point.
• src/App.vue: Root component containing the <Router /> or main routing logic.
• src/pages/: Directory for individual route components (e.g., HomePage.vue, AboutPage.vue).
• src/components/: Shared UI components like Navigation.vue.

Sources: examples/example/README.md:33-45, examples/example/index.html:10-12

Performance Benchmarks

Installation and adoption of wouter-vue provides significant performance benefits over standard solutions like vue-router for high-traffic or resource-constrained environments:

• Bundle Size: ~7.9KB gzipped (72% smaller than vue-router).
• Throughput: 117 req/s vs 68 req/s (+72% faster).
• Total Requests: Handles 83% more requests in the same timeframe.

Sources: README.md:46-68

In summary, getting started with wouter-vue involves installing the package, optionally configuring the Vite plugin for large route sets, and using the Composition-API-friendly components to define navigation and view mapping.

Sources: README.md:112-115, examples/README.md:1-15