Router Component

Relevant source files

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

• src/components/Router.tsx
• src/components/Route.tsx
• test/router.test.ts
• test/route.test.ts
• test/nested-route.test.ts
• README.md

The Router component is a fundamental building block of the wouter-vue library. It provides a routing context for its children, managing the base path, the location hook, and the path parser. While wouter-vue is designed to be "minimalist-friendly" and allows using hooks like useLocation without a top-level router, the <Router /> component is essential for advanced scenarios like nested routing, custom base paths, and Server-Side Rendering (SSR).

Sources: README.md:1-20, src/components/Router.tsx:1-15

Component Architecture

The Router component acts as a provider in the Vue 3 Composition API ecosystem. It gathers configuration through props and provides a reactive RouterObject to all descendant components (such as <Route /> and <Link />) using Vue's provide mechanism.

Data Flow and Context Provisioning

When a Router is initialized, it merges configuration from its own props with any parent Router context it might be nested within. This allows for hierarchical routing where base paths are stacked.

The diagram above illustrates how the Router component resolves its configuration and distributes it to the rest of the application.
Sources: src/components/Router.tsx:40-75, test/router.test.ts:35-50

Configuration Options

The Router component accepts several props that define the behavior of the routing tree under its scope.

Prop	Type	Default	Description
base	string	''	A prefix for all paths within this router. In nested routers, this stacks with the parent's base.
hook	Function	useBrowserLocation	A hook that manages the current location state (e.g., hash-based, memory-based).
parser	Function	pathToRegexp	A function used to compile and match route patterns.
ssrPath	string	undefined	The initial path used during Server-Side Rendering.

Sources: src/components/Router.tsx:18-35, README.md:45-55

Nested Routing and Base Paths

One of the primary functions of the Router component is managing the base path. When routers are nested, the base paths are concatenated, ensuring that children can use relative paths.

Base Path Stacking Logic

If a <Router base="/app"> contains another <Router base="/admin">, the effective base for the inner router becomes /app/admin. This behavior ensures that a <Link href="/dashboard"> inside the innermost router correctly points to /app/admin/dashboard.

This sequence shows the recursive resolution of the base path during the mounting phase of nested routers.
Sources: src/components/Router.tsx:55-65, test/router.test.ts:1-30

Implementation Detail: The nest Prop

While the Router component handles the base path logic, the <Route /> component often triggers the creation of nested routers automatically when the nest prop is used. This allows for relative route matching within complex UI structures.
Sources: src/components/Route.tsx:120-140, test/nested-route.test.ts:50-70

Location Hooks Integration

The Router component is decoupled from the browser's URL through the hook prop. This allows the same component to be used in different environments:

1. Browser Environment: Uses the default useBrowserLocation (Standard History API).
2. Hash Routing: Can be configured with useHashLocation for legacy browser support or specific deployment requirements.
3. Testing/Non-Browser: Uses memoryLocation to simulate routing in memory without affecting the window location.
4. SSR: Uses the ssrPath to provide a static location during the rendering cycle on the server.

// Example: Using a memory hook for testing
const { hook } = memoryLocation({ path: "/custom" });

const wrapper = mount(Router, {
  props: { hook },
  slots: { default: () => h(TestComponent) }
});

Sources: test/router.test.ts:53-70, src/components/Router.tsx:48-52

Technical Implementation Summary

The component is implemented using the defineComponent factory and the setup function for optimal performance and TypeScript support.

export const Router = defineComponent({
  name: 'Router',
  props: {
    base: { type: String, default: '' },
    hook: { type: Function },
    ssrPath: { type: String },
    parser: { type: Function },
  },
  setup(props, { slots }) {
    const parentRouter = inject(RouterDataKey, null);
    // ... logic to merge bases and hooks ...
    const router = reactive({ ...resolvedOptions });
    provide(RouterDataKey, router);
    return () => slots.default?.();
  }
})

Sources: src/components/Router.tsx:18-80

Conclusion

The Router component serves as the configuration engine for wouter-vue. By utilizing Vue 3's dependency injection system, it establishes a predictable environment for navigation and route matching, supporting both simple flat structures and complex hierarchical applications with ease. Its ability to stack base paths and accept custom location hooks makes it highly adaptable for various deployment targets including SSR and unit testing.

Sources: README.md:25-40, src/components/Router.tsx