# @microsoft/webui-router
Build-time compiled router for [WebUI](https://github.com/microsoft/webui) apps. Routes, cache tags, invalidation graphs, pending states, and error boundaries are declared as HTML attributes, validated by the Rust compiler, and baked into the binary protocol — zero runtime JavaScript for routing policy.
Uses the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API) for client-side transitions. The server provides the matched route chain; the client does not perform route matching.
> 📖 **Full documentation at [microsoft.github.io/webui](https://microsoft.github.io/webui)** — see the [Routing Guide](https://microsoft.github.io/webui/guide/concepts/routing) for setup and usage.
## How It Works
1. **Server renders the full page** - the matched route chain is SSR'd with declarative shadow roots. The page is interactive before JavaScript loads.
2. **Hydration completes** - WebUI Framework hydrates shell components.
3. **Router starts** - reads the SSR route bootstrap data and intercepts link clicks via the Navigation API. The router never imports framework code.
4. **Client-side navigation** - fetches a JSON partial from the server, which includes the matched route chain. The client diffs old vs new chain and mounts only the changed component. Parent components stay mounted.
Authored route components use their registered classes. Scriptless route
components also navigate without a full page reload when the application loads
`@microsoft/webui-framework`, which mounts the templates published by the
router.
## Installation
```bash
npm install @microsoft/webui-router
```
## Quick Start
**1. Add `` in your ``:**
```html
```
All WebUI apps with routes **must** include ``. Without it, relative asset paths (CSS, JS) break on nested routes — the browser resolves `app.css` against `/contacts/123/` → `/contacts/app.css` instead of `/app.css`.
For sub-path deployments, set the base to the sub-path: ``.
**2. Declare nested routes in `index.html`:**
```html
```
Child routes use **relative paths** (no leading `/`). The nesting is the route tree.
**2. Use `` in parent components:**
```html
```
`` marks where child route content renders. The nav and footer persist across navigations.
The paired form `` is also supported, but outlets are empty and
the self-closing form is preferred.
On initial SSR, styles for the matched route chain that target the Document are
applied before ``, including Link-mode bundled chunks. Styles targeting a
ShadowRoot remain tree-local; Link mode preloads them from the head and installs
the applying stylesheet inside that root. Inactive route styles stay deferred.
**3. Start the router after hydration:**
```typescript
import '@microsoft/webui-framework';
import { Router } from '@microsoft/webui-router';
import './app-shell.js';
window.addEventListener('webui:hydration-complete', () => {
Router.start({
loaders: {
'home-page': () => import('./pages/home-page.js'),
'user-list': () => import('./pages/user-list.js'),
'user-detail': () => import('./pages/user-detail.js'),
},
});
});
```
Components in `loaders` are lazy-loaded on first navigation. Components not
listed are assumed eagerly loaded when already registered. Scriptless route
templates can accept server-provided partial state through the framework
without empty `.ts` files. Add a same-named module only when a route owns
events, lifecycle code, decorators, or imperative APIs. If no runtime registers a destination tag, the router safely
falls back to a full document request.
## Nested Routes
Routes nest to any depth. Each parent uses `` for child content:
```html
```
Navigating from `/settings/profile` to `/settings/billing` only remounts the billing component — `app-shell` and `settings-page` stay mounted with their state preserved.
### The `exact` Attribute
- **Leaf routes** (no children): add `exact`
- **Parent routes** (have ``): omit `exact`
Without `exact`, a route matches any URL that starts with its path — which is what parent routes need.
### The `keep-alive` Attribute
Preserve a component across navigations instead of destroying and recreating it:
```html
```
When the user navigates away from a `keep-alive` route and returns, the existing component is reused. Its DOM and local state (scroll position, input values, timers) survive the round trip.
**State is preserved by default.** The router only updates route param and query param attributes on reactivation. This means your component's `@observable` properties, scroll position, form inputs, and any client-computed state all survive.
To refresh data on reactivation, define a [route loader](#route-loaders):
```typescript
export class MailView extends WebUIElement {
@observable messages = [];
static async loader({ signal }: RouteLoaderContext) {
const resp = await fetch('/api/messages', { signal });
return { messages: await resp.json() };
}
}
```
### Route Loaders
Define a static `loader()` on a component to fetch data from a custom source instead of using server-provided state:
```typescript
import type { RouteLoaderContext } from '@microsoft/webui-router';
export class LiveDashboard extends WebUIElement {
@observable source = '';
@observable metrics = {};
static async loader({ params, query, signal }: RouteLoaderContext) {
const resp = await fetch(`/api/dashboard/${params.id}`, { signal });
return { source: 'client', metrics: await resp.json() };
}
}
```
**How it works:**
- The router checks each route component's constructor for a static `loader()` method
- Loaders run **before** the view transition — results are ready for synchronous DOM commit
- The loader receives route `params`, parsed `query`, and an `AbortSignal` tied to the navigation
- If a loader fails, the router falls back to server-provided state with a console warning
- Loaders run on both SSR bootstrap and SPA navigations for consistency
**When to use loaders:**
- WebSocket-driven dashboards that manage their own data stream
- Components that fetch from a different API than the SSR server
- Keep-alive components that need fresh data on reactivation
- Any component that wants full control over its state source
### Base Path (Sub-Path Deployment)
Every WebUI app with routes needs `` in its `` (see Quick Start above). This ensures relative asset paths resolve correctly on nested routes.
For sub-path deployments (e.g., `https://example.com/commerce/`), change it to the sub-path:
```html
```
The `` tag is a core web platform feature. It makes the browser resolve all relative URLs (``, ``, `fetch()`) against the base path. The router detects it at startup and uses it to strip/prepend the prefix on navigation URLs.
When using `webui serve --base-path /commerce/`, the `` tag is emitted automatically.
### Preload on Hover
Opt-in speculative fetching for instant click navigation:
```typescript
Router.start({ preload: true });
```
When enabled, the router prefetches JSON partials (templates, CSS, state) when the user hovers over internal links. On click, the cached result is used immediately. Preloaded entries are stored in the [tagged cache](#tagged-cache) with a 5-second minimum freshness. Only mouse pointers trigger preload.
The pre-hydration API is framework-agnostic:
```typescript
import { prepareRoutePreload } from '@microsoft/webui-router/preload.js';
const prepared = prepareRoutePreload({
onIntent: () => startYourHydrationRuntime(),
});
await hydrationReady;
Router.start({ ...config, preload: prepared });
```
It buffers one hovered partial as bounded raw bytes before any hydration
framework starts, then transfers the in-flight/completed response into normal
navigation without a second request or early template parsing. WebUI Framework,
FAST, and other runtimes start through `onIntent`, then pass the same handle to
the router after their own readiness lifecycle.
### Tagged Cache
Cache partial responses with server-provided tags for precise invalidation:
Cache and preload are optional runtime tiers. The default `Router.start()` path
does not import the cache implementation until `cache` or `preload` opts in.
```typescript
Router.start({
cache: {
staleTime: 30_000, // ms before refetch (default: 0 = disabled)
gcTime: 300_000, // ms before eviction from memory (default: 5 min)
maxEntries: 50, // LRU cap (default: 50)
},
});
```
Declare cache tags on routes as HTML attributes:
```html
```
The `{threadId}` placeholder is resolved at render time by the Rust handler. The server includes resolved `cacheTags` in the JSON partial. On revisit within `staleTime`, the cached response is used instantly.
### Tag-Based Invalidation
Declare which tags a route invalidates after mutations:
```html
```
Programmatic invalidation:
```typescript
Router.invalidateTags(['inbox', 'thread:42']); // evict by tag
Router.invalidate('/email/42'); // evict by path
Router.invalidate(); // evict everything
```
### Mutation Actions
The write counterpart to `static loader()`. Enable `Router.start({ actions: true })` to make the router intercept `