@vielzeug/wayfinder

Lightweight, type-safe client-side router with nested routes, data loading, middleware, and named navigation.

Package: @vielzeug/wayfinder    Category: Routing

Key exports: createRouter, createBrowserHistory, createMemoryHistory, redirectTo

When to use: Framework-agnostic client-side router with typed params, async data loading, middleware, leave guards, and View Transitions support.

Related: @vielzeug/ripple · @vielzeug/ward · @vielzeug/herald

@vielzeug/wayfinder is part of Vielzeug and ships as a zero-dependency TypeScript package with ESM+CJS output.

What You Get

• Declarative route tables with nested names (dashboard.settings)
• Named and raw-path navigation through one navigate() API
• Route middleware, data loaders, and lazy route modules
• Global beforeLeave leave guards with optional route scoping
• component + meta + data payloads on matched branch state
• Per-match status for granular loading/streaming feedback in nested layouts
• Streaming data loaders via async generators
• Declarative notFound fallback route
• Browser and memory history drivers
• redirectTo() middleware helper
• SSR-compatible match() for data prefetching without side effects
• waitFor(name) for testing and lifecycle coordination

Installation

pnpm add @vielzeug/wayfinder
npm install @vielzeug/wayfinder
yarn add @vielzeug/wayfinder

Quick Start

import { createRouter } from '@vielzeug/wayfinder';

const router = createRouter({
  routes: {
    home: { path: '/' },
    dashboard: {
      path: '/dashboard',
      children: {
        index: { index: true },
        settings: {
          path: 'settings',
          data: async () => fetchSettings(),
        },
      },
    },
  },
  notFound: {
    component: NotFoundPage,
  },
});

// React to state changes:
router.subscribe((state) => {
  const leaf = state.matches.at(-1);
  render(leaf?.component, leaf?.data);
});

await router.navigate({ name: 'dashboard.settings' });

Documentation

• Overview
• Usage Guide
• API Reference
• Examples
• React Integration Example
• Vue Integration Example
• Svelte Integration Example

License

MIT © Helmuth Saatkamp — part of the Vielzeug monorepo.