![build](https://github.com/Wildhoney/Wayfinder/actions/workflows/ci.yml/badge.svg) Strongly-typed React router built on the [Navigation API](https://web.dev/blog/baseline-navigation-api). No outlets, no nesting — just routes, data, and a URL builder. react-wayfinder demo

Home

Loading…

{error.message}

; }, }), ]); createRoot(document.getElementById("root")!).render( ); ``` Inside the tree, read the typed navigation handle via `router.useContext()`: ```tsx import { router } from "./router"; function Header() { const context = router.useContext(); return User 42; } ``` Routes **without** a `data` function pass `params`, `url`, and `router` to `match`. Routes **with** a `data` function receive a discriminated `args` union keyed on `status` — destructure `{ status, params, data, error }` at the top and branch on `status`. TypeScript narrows the sibling `data` / `error` fields per branch (TS 5.4+ correlated-narrowing), so inside `status === "ready"` the `data` is the typed payload, inside `status === "error"` the `error` is `Error`, and neither is meaningful while `status === "loading"`. Use `"*"` as a catch-all for unmatched routes; anonymous routes (wildcards, untracked redirects) omit `name`. ## Navigation state Wrap any navigable element in `` to get `href`, `active`, `pending`, and `handler`. For `` tags, use `href` — the Navigation API intercepts the click natively. For ` )} ); } ``` | Property | Type | Description | |---|---|---| | `href` | `string` | The resolved URL string — use as `href` on `` tags | | `active` | `boolean` | `true` if this href matches the currently rendered route | | `pending` | `boolean` | `true` while navigating to this `href` | | `handler` | `(event?) => void` | Attach as `onClick` on ` )} ``` ## Programmatic navigation `router.useContext()` returns a `navigate` object for navigating outside of a ``. Each method takes a pre-built href — pair it with the `url` builders to keep call sites type-safe: ```tsx import { router } from "./router"; function NavigationButtons() { const context = router.useContext(); return ( <> ); } ``` | Method | Behaviour | |---|---| | `navigate.push(href)` | Push a new history entry (the default action). | | `navigate.replace(href)` | Swap the current history entry in place — useful for canonicalisation and login redirects. | | `navigate.back()` | Traverse one entry back, equivalent to the browser back button. | | `navigate.forward()` | Traverse one entry forward. | | `navigate.reload()` | Re-run the current route's `data` function — same URL, no new history entry. | The same `context` handle is passed to every route's `match` and `redirect` callback — so you can navigate type-safely from places where hooks aren't available. If you'd rather not import a specific `router` definition, use the standalone `useRouter()` hook. Pass your routes type as the generic to get fully-typed builders without binding to a particular host: ```tsx import { useRouter } from "react-wayfinder"; import type { Routes } from "@app/router"; function Header() { const context = useRouter(); return Home; } ``` ## Redirects Return `` from a route's `match` callback to replace the current history entry with another URL. Use it as a catch-all or to canonicalise an incomplete URL. `` runs the navigation once on mount via `useEffect`, so re-renders of the surrounding `` don't re-fire it. ```tsx import { Router, Redirect, route } from "react-wayfinder"; export enum Routes { Cat = "/cats/:index", } export const router = Router([ route({ name: "cat", url: Routes.Cat, match({ params }) { return ; }, }), route({ url: "/cats", match: () => , }), route({ url: "*", match: () => , }), ]); ``` `` always uses `history: "replace"`, so the browser back button skips the redirected-from URL. Pair it with `router.url.X(...)` to keep targets type-safe — no `as` cast required. ## Cancellation Every `data` function receives an `AbortSignal` via `signal`. The signal is aborted when: - The user presses **Escape** during a pending navigation - A new navigation supersedes the current one (clicking User 2 while User 1 is loading) ```tsx async data({ params, signal }) { const response = await fetch(`/api/users/${params.id}`, { signal }); return response.json(); } ``` When cancelled, the router restores the previous route and URL — no stale state. Escape only fires when a `data` function is in-flight; pressing Escape after navigation completes does nothing. ## Caching Every `data` function receives `cache` — the previously loaded data for that route, or `undefined` on first visit. The router always calls `data`; you decide the caching strategy: ```tsx async data({ params, signal, cache }) { if (cache) return cache; const response = await fetch(`/api/users/${params.id}`, { signal }); return response.json(); } ``` Previously visited routes are preserved in the DOM using React [``](https://react.dev/reference/react/Activity) — their component state, scroll position, and form inputs survive navigation. The example app's `/feed` route demonstrates this: scroll down to load more items via the infinite-scroll `data` function, navigate away, then come back — your scroll position and every loaded item are still there. ## View transitions The router automatically wraps route swaps in `document.startViewTransition()` when the browser supports it. It sets `data-direction="forward"` or `data-direction="back"` on `` so you can style direction-aware animations with CSS: ```css :root { --transition-duration: 250ms; } [data-direction="forward"]::view-transition-old(root) { animation: slide-out-left var(--transition-duration) ease-in-out; } [data-direction="forward"]::view-transition-new(root) { animation: slide-in-from-right var(--transition-duration) ease-in-out; } [data-direction="back"]::view-transition-old(root) { animation: slide-out-right var(--transition-duration) ease-in-out; } [data-direction="back"]::view-transition-new(root) { animation: slide-in-from-left var(--transition-duration) ease-in-out; } ``` Direction is detected via the Navigation API — `"back"` when traversing to a lower history index, `"forward"` otherwise. Cancel clears the `data-direction` attribute to prevent unwanted animations. ## Router modes The `mode` prop on `` controls how the router transitions between routes that fetch data: ```tsx ``` | Mode | Behaviour | |---|---| | `"deferred"` (default) | Keeps the previous page on screen while the `data` function runs. Inline spinners via `` show on the clicked element. | | `"immediate"` | Switches to the new route immediately with `status: "loading"` so you can render skeletons. Escape restores the previous route from the preserved ``. | ## Base path When deploying to a sub-path (e.g. `https://example.com/my-app/`), pass `base` to `` so the router strips the prefix before matching — route patterns stay root-relative. The base is also baked into every `context.url.X(...)` builder so call sites never need to remember to prefix manually: ```tsx ``` ```tsx function Link() { const context = router.useContext(); // with base="/app", builders return base-prefixed paths automatically return User 42; // "/app/users/42" } ``` ## Nested routes `` can be nested freely. A top-level navigation bar uses `` for each link, and the page it renders can nest its own `` instances for sub-navigation. Each `` independently tracks `active` and `pending` for its own `href`: ```tsx function Contact() { const context = router.useContext(); return ( <> ); } ``` The top-level "Contact" link uses a custom `active` predicate so it stays highlighted regardless of which sub-tab is selected. Each nested `` uses the default exact match. ## Shared components In a monorepo where multiple apps share React components, those components can't import a single `router` definition — each app declares its own `Routes` enum. Use `shared.useContext()` and pass the **union of `typeof Routes`** as the generic: ```tsx // apps/web/router.ts import { Router, route } from "react-wayfinder"; export enum Routes { Home = "/", Dashboard = "/dashboard", } export const router = Router([ route({ name: "home", url: Routes.Home, match: () => /* ... */ null }), route({ name: "dashboard", url: Routes.Dashboard, match: () => /* ... */ null }), ]); ``` ```tsx // apps/mobile/router.ts — symmetrical, different routes export enum Routes { Home = "/", Profile = "/profile", } ``` ```tsx // shared/header.tsx — works under any host import { shared } from "react-wayfinder"; import * as web from "@app/web/router"; import * as mobile from "@app/mobile/router"; type AnyRoutes = typeof web.Routes | typeof mobile.Routes; export function Header() { const context = shared.useContext(); return Home; // present in both arms — no narrowing needed } ``` ### Narrowing with `is*App` type guards When a shared component needs to render app-specific links, write a type guard per host and let TypeScript narrow the routes union to a single arm. The guard inspects the runtime handle and returns a `context is Router` predicate — everything inside the `if` block then sees one concrete set of routes: ```tsx import type { Router } from "react-wayfinder"; import * as web from "@app/web/router"; import * as mobile from "@app/mobile/router"; type AnyRoutes = typeof web.Routes | typeof mobile.Routes; // `Dashboard` only exists on the web app — that's our discriminator function isWebApp(context: Router): context is Router { return "dashboard" in context.url; } function isMobileApp(context: Router): context is Router { return "profile" in context.url; } export function ContextLink() { const context = shared.useContext(); if (isWebApp(context)) { // narrowed to Router return Dashboard; } if (isMobileApp(context)) { return Profile; } return null; } ``` For the **same key with different params** across apps, every builder also carries its source pattern on `.pattern`. Compare the literal inside an `is*App` guard to keep the narrowing centralised: ```tsx enum SoloRoutes { User = "/users/:id" } enum TeamRoutes { User = "/teams/:tid/users/:uid" } function isSoloApp( context: Router, ): context is Router { return context.url.user.pattern === "/users/:id"; } ``` Reach for `shared.useContext` **only** when a component must support more than one host. Single-app code should stick with `router.useContext()` — the routes are captured automatically and the call site is one generic shorter.