Waymark

A lightweight, type-safe router for React that just works.

Waymark is a routing library for React built around three core ideas: type safety, simplicity, and minimal overhead.

Fully type-safe - Complete TypeScript inference for routes, path params, and search params
Zero config - No build plugins, no CLI, no codegen, no config files, very low boilerplate
Familiar API - If you've used React Router or TanStack Router, you'll feel at home
3.6kB gzipped - Extremely lightweight with just one 0.4kB dependency, so ~4kB total
Feature packed - Search param validation, lazy loading, data preloading, SSR, error boundaries, etc.
Not vibe-coded - Built with careful design and attention to detail by a human
Just works - Define routes, get autocomplete everywhere

Showcase

Here's what routing looks like with Waymark:

import { route, RouterRoot, Outlet, Link, useParams } from "waymark";
 
// Layout
const layout = route("/").component(() => (
  <div>
    <nav>
      <Link to="/">Home</Link>
      <Link to="/users/:id" params={{ id: "42" }}>
        User
      </Link>
    </nav>
    <Outlet />
  </div>
));
 
// Pages
const home = layout.route("/").component(() => <h1>Home</h1>);
 
const user = layout.route("/users/:id").component(function UserPage() {
  const { id } = useParams(user); // Fully typed
  return <h1>User {id}</h1>;
});
 
// Setup
const routes = [home, user];
 
function App() {
  return <RouterRoot routes={routes} />;
}
 
declare module "waymark" {
  interface Register {
    routes: typeof routes;
  }
}

Everything autocompletes and type-checks automatically. No heavy setup, no magic, just a simple API that gets out of your way.

Installation

npm install waymark

Waymark requires React 18 or higher.

Defining routes

Routes are created using the route() function, following the builder pattern. You pass it a path and chain methods to configure the route.

The .component() method tells the route what to render when the path matches. It takes a React component and returns a new route instance with that component attached:

import { route } from "waymark";
 
const home = route("/").component(HomePage);
const about = route("/about").component(AboutPage);

Routes support dynamic segments (path params) using the :param syntax:

const required = route("/posts/:id");
const nested = route("/org/:orgId/team/:teamId");
const optional = route("/book/:title?");
const suffix = route("/movies/:title.(mp4|mov)");

And wildcard segments that capture everything after a certain point:

const notFound = route("/*").component(NotFoundPage);
const files = route("/files/*").component(FileBrowser);
const optional = route("/books/*?").component(FileBrowser);

Route building is immutable: every method on a route returns a new route instance, which means you can branch off at any point to create variations or nested routes without affecting the original.

Nested routes and layouts

Nesting is the core mechanism for building layouts and route hierarchies in Waymark. When you call .route() on an existing route, you create a child route that inherits everything from the parent: its path as a prefix, its params, its components, etc.

Here's how it works. Start with any route:

const dashboard = route("/dashboard").component(DashboardLayout);

Then create child routes by calling .route() on it:

const overview = dashboard.route("/").component(Overview);
const settings = dashboard.route("/settings").component(Settings);
const profile = dashboard.route("/profile").component(Profile);

The child routes combine the parent's path pattern with their own. So overview has the full pattern /dashboard, settings has /dashboard/settings, and profile has /dashboard/profile.

The parent component must render an <Outlet /> where child routes should appear:

function DashboardLayout() {
  return (
    <div>
      <Sidebar />
      <main>
        <Outlet />
      </main>
    </div>
  );
}

When the URL is /dashboard/settings, Waymark renders DashboardLayout with Settings inside the outlet. The layout stays mounted (and doesn't even rerender) as users navigate between child routes.

You can nest as deep as you need:

const app = route("/").component(AppShell);
const dashboard = app.route("/dashboard").component(DashboardLayout);
const settings = dashboard.route("/settings").component(SettingsLayout);
const security = settings.route("/security").component(SecurityPage);

For the path /dashboard/settings/security, this renders:

AppShell
  └── DashboardLayout
        └── SettingsLayout
              └── SecurityPage

Each level must include an <Outlet /> to render the next level.

Setting up the router

Before setting up the router, you need to collect your navigable routes into an array. When building nested route hierarchies, you'll often create intermediate parent routes solely for grouping and shared layouts. These intermediate routes shouldn't be included in your routes array - only the final, navigable routes should be:

// Intermediate route used for hierarchy
const layout = route("/").component(Layout);
 
// Navigable routes that users can actually visit
const home = layout.route("/").component(Home);
const about = layout.route("/about").component(About);
 
// Collect only the navigable routes
const routes = [home, about]; // ✅ Don't include `layout`

This makes sure that only actual pages can be matched and appear in autocomplete. The intermediate routes still exist as part of the hierarchy, they just aren't directly navigable. Note that the order of routes in the array doesn't matter - Waymark uses a ranking algorithm to pick the most specific match.

The RouterRoot component is the entry point to Waymark. It listens to URL changes, matches the current path against your routes, and renders the matching route's component hierarchy.

There are two ways to set it up. The simplest is passing your routes array directly to RouterRoot. This creates a router instance internally (accessible via useRouter):

import { RouterRoot } from "waymark";
 
const routes = [home, about];
 
function App() {
  return <RouterRoot routes={routes} />;
}

You can also pass a basePath if your app lives under a subpath:

<RouterRoot routes={routes} basePath="/my-app" />

The second approach is to create a Router instance outside of React. This gives you a global router instance that can be accessed from non-React contexts (e.g., utility functions, service modules, or other non-React code):

import { Router, RouterRoot } from "waymark";
 
const router = new Router({ routes });
 
// Now you can navigate from anywhere
router.navigate({ to: "/about" });
 
// And pass the instance to RouterRoot
function App() {
  return <RouterRoot router={router} />;
}

For full type safety across your app, register your routes using TypeScript's module augmentation. This is a required step for proper autocompletion and type checking:

declare module "waymark" {
  interface Register {
    routes: typeof routes;
  }
}

With this in place, Link, navigate, useParams, useSearch, and other APIs will know exactly which routes exist and what input they expect, and you're good to go.

Code organization

There's no prescribed way to organize your routing code. Since Waymark isn't file-based routing, the structure is entirely up to you.

That said, here's a pattern that tends to work well: define each route and its component in the same file, then export the route. This keeps everything related to that page in one place:

// pages/home.tsx
import { route } from "waymark";
 
export const home = route("/").component(Home);
 
function Home() {
  return <div>Home page</div>;
}

// pages/about.tsx
import { route } from "waymark";
 
export const about = route("/about").component(About);
 
function About() {
  return <div>About page</div>;
}

Then in your root app component file, import all the routes, register them with module augmentation, and render RouterRoot:

// app.tsx
import { RouterRoot } from "waymark";
import { home } from "./pages/home";
import { about } from "./pages/about";
 
const routes = [home, about];
 
export function App() {
  return <RouterRoot routes={routes} />;
}
 
declare module "waymark" {
  interface Register {
    routes: typeof routes;
  }
}

But again, this is just one approach. You could keep all routes in a single file, split them by feature, organize them by route depth, whatever fits your project. Waymark doesn't care where the routes come from or how you structure your files.

Path params

Dynamic segments in route patterns become typed path params. Define them with a colon prefix. They can also be made optional.

const post = route("/posts/:id").component(PostPage);
const comment = route("/posts/:postId/comments/:commentId?").component(
  CommentPage
);

Access parameters with useParams, passing the route pattern or object as an argument:

function PostPage() {
  const { id } = useParams(post);
  // id is typed as string
 
  const { id } = useParams("/posts/:id");
  // Also works
}
 
function CommentPage() {
  const { postId, commentId } = useParams(comment);
  // postId: string
  // commentId?: string | undefined
}

Wildcard segments capture everything after a slash. They're defined with * and accessed with the key "*":

const files = route("/files/*").component(FileBrowser);
 
function FileBrowser() {
  const params = useParams(files);
  const path = params["*"]; // e.g., "documents/report.pdf"
}

Search params

Basic usage

Search params (the ?key=value part of URLs) can be typed and validated using the .search() method on a route. You can pass either a Standard Schema validator like Zod, or a plain validation function.

With Zod:

import { z } from "zod";
 
const searchPage = route("/search")
  .search(
    z.object({
      q: z.string().catch(""),
      page: z.coerce.number().catch(1)
    })
  )
  .component(SearchPage);

With a plain function:

const searchPage = route("/search")
  .search(raw => ({
    q: String(raw.q ?? ""),
    page: Number(raw.page ?? 1)
  }))
  .component(SearchPage);

Since you can't control what users put in the URL, your validator should handle missing or malformed values gracefully - validate and normalize rather than reject.

Access validated search params with useSearch, which returns a tuple of the current values and a setter function:

function SearchPage() {
  const [search, setSearch] = useSearch(searchPage);
  // search.q: string
  // search.page: number
}

The setter merges your updates with existing values:

setSearch({ page: 2 }); // Only updates page
setSearch(prev => ({ page: prev.page + 1 })); // Increment page

Pass true as the second argument to replace the history entry instead of pushing:

setSearch({ page: 1 }, true);

JSON-first approach

Waymark uses a JSON-first approach for search params, similar to TanStack Router. When serializing and deserializing values from the URL:

Plain strings that aren't valid JSON are kept as-is (and URL-encoded): "John" → ?name=John → "John"
Everything else is JSON-encoded (then URL-encoded):
- true → ?enabled=true → true
- "true" → ?enabled=%22true%22 → "true"
- [1, 2] → ?filters=%5B1%2C2%5D → [1, 2]
- 42 → count=42 → 42

This means you can store complex data structures like arrays and objects in search params without manual serialization. When reading from the URL, Waymark automatically parses JSON values back to their original types.

The resulting parsed object is what gets passed to the .search() function or schema on the route builder. It's typed as Record<string, unknown>, which is why validation is useful - it lets you transform these unknown values into a typed, validated shape that your components can safely use.

Inheritance

When you define search params with a validator on a route, all child routes automatically inherit that validator along with its typing.

Here's how it works. Start with a parent route that defines a search param:

const dashboard = route("/dashboard")
  .search(
    z.object({
      view: z.enum(["grid", "list"]).catch("grid")
    })
  )
  .component(DashboardLayout);

Any child route created from dashboard inherits the view search param and its validation:

const projects = dashboard.route("/projects").component(ProjectsPage);
 
function ProjectsPage() {
  const [search] = useSearch(projects);
  // search.view is typed as "grid" | "list"
}

If a child route needs additional search params, define a new validator with .search(). Your validator receives the raw params from the URL merged with the parent's already-validated params. After validation, your result is combined with the parent's validated params to produce the final search params object.

In practice, this means you only need to validate the new params you're adding - the parent's params are automatically included in the final result:

const projects = dashboard
  .route("/projects")
  .search(
    z.object({
      status: z.enum(["active", "archived"]).catch("active")
    })
  )
  .component(ProjectsPage);
 
function ProjectsPage() {
  const [search] = useSearch(projects);
  // search.view: "grid" | "list" (from parent)
  // search.status: "active" | "archived" (from child)
}

Idempotency requirement

The validation function or schema you pass to .search() must be idempotent, meaning fn(fn(x)) should equal fn(x).

When you read search params, the values are passed through your validator. When you update search params, the navigation APIs expect values in that same validated format, which are then JSON-encoded back into the URL. On the next read, those encoded values are decoded and passed through your validator again - meaning your validator may receive its own output as input.

Navigation

The Link component

The Link component renders an anchor tag that navigates without a full page reload. It accepts a to prop that can be either a route pattern string or a route object:

<Link to="/about">About</Link>
<Link to={about}>About</Link>

When the route has non-optional path params, you must provide the params prop:

<Link to="/posts/:id" params={{ id: postId }}>
  View post
</Link>

And if the route has search params defined, you can pass them too:

<Link to={userProfile} params={{ id: "42" }} search={{ tab: "posts" }}>
  User posts
</Link>

To replace the current history entry instead of pushing a new one, use replace:

<Link to="/login" replace>
  Login
</Link>

You can also pass arbitrary state that will be available via useLocation().state:

<Link to="/checkout" state={{ from: "cart" }}>
  Checkout
</Link>

The asChild prop lets you use your own component while keeping Link's behavior:

<Link to="/profile" asChild>
  <MyCustomAnchor>Go to profile</MyCustomAnchor>
</Link>

Active state detection

Links automatically track whether they match the current URL. When active, they receive a data-active="true" attribute and can apply different styles.

By default, a link is considered active if the current path starts with the link's target (called "loose matching"). This means a link to /dashboard stays active on /dashboard/settings. To require an exact match, use the strict prop:

<Link to="/dashboard">Active on /dashboard and child routes</Link>
<Link strict to="/dashboard">Active only on /dashboard</Link>

You can style active links using the data attribute in CSS:

.nav-link[data-active="true"] {
  font-weight: bold;
  color: blue;
}

Or use the activeClassName and activeStyle props directly:

<Link
  to="/dashboard"
  className="nav-link"
  activeClassName="active"
  style={{ opacity: 0.7 }}
  activeStyle={{ opacity: 1 }}
>
  Dashboard
</Link>

Route preloading

Links can optionally trigger route preloading before navigation occurs. When preloading is enabled, any lazy-loaded components (defined with .lazy()) and preload functions (defined with .preload()) are called early. This improves perceived performance by loading component bundles and running preparation logic like prefetching data ahead of time.

The preload prop controls when preloading happens:

preload="intent" preloads when the user shows intent to navigate by hovering or focusing the link. This is the most common choice as it balances eager loading with not wasting bandwidth:

<Link to="/heavy-page" preload="intent">
  Heavy page
</Link>

preload="render" preloads as soon as the link mounts. Use this for routes you're confident the user will visit:

<Link to="/next-step" preload="render">
  Next step
</Link>

preload="viewport" uses an Intersection Observer to preload when the link scrolls into view. Good for links further down the page and mobile:

<Link to="/section" preload="viewport">
  See more
</Link>

preload={false} disables preloading entirely. This is the default.

To prevent unwanted preloads from quick hover/focus interactions, Link waits 50ms before triggering. You can customize this with preloadDelay:

<Link to="/heavy-page" preload="intent" preloadDelay={100}>
  Heavy page
</Link>

You can also preload programmatically using router.preload():

const router = useRouter();
router.preload({ to: userProfile, params: { id: "42" } });

To set a preload strategy globally for all links in your app, see Global link configuration.

Programmatic navigation

For navigation triggered by code rather than user clicks, use the useNavigate hook:

import { useNavigate } from "waymark";
 
function LoginForm() {
  const navigate = useNavigate();
 
  const onSubmit = async () => {
    await login();
    navigate({ to: "/dashboard" });
  };
 
  // ...
}

The navigate function accepts the same navigation options as Link:

navigate({ to: userProfile, params: { id: "42" }, search: { tab: "posts" } });
navigate({ to: "/login", replace: true });
navigate({ to: "/checkout", state: { from: "cart" } });

To go back or forward in history, pass a number:

navigate(-1); // Go back
navigate(1); // Go forward
navigate(-2); // Go back two steps

You can also access the router directly via useRouter() (or import the router if created outside of React) and call its navigate method, which works the same way:

router.navigate({ to: "/login" });

For unsafe navigation that bypasses type checking, you can pass url instead of to, params and search. This is useful when you don't know the target URL statically (e.g., URLs from user input or API responses):

// Type-safe navigation
navigate({ to: userProfile, params: { id: "42" } });
 
// Unsafe navigation - no type checking
navigate({ url: "/some/path?tab=settings" });
navigate({ url: "/callback", replace: true, state: { data: 123 } });

Declarative navigation

For redirects triggered by rendering rather than events, use the Navigate component. It navigates as soon as it mounts, making it useful for conditional redirects based on application state:

import { Navigate } from "waymark";
 
function ProtectedPage() {
  const { isAuthenticated } = useAuth();
 
  if (!isAuthenticated) {
    return <Navigate to="/login" replace />;
  }
 
  return <div>Protected content</div>;
}

The Navigate component accepts the same navigation props as the Link component:

<Navigate to="/users/:id" params={{ id: "42" }} search={{ tab: "posts" }} />
<Navigate to="/home" replace />
<Navigate to={checkout} state={{ from: "cart" }} />

Note that Navigate uses useLayoutEffect internally to ensure the navigation is triggered before the browser repaints the screen.

Lazy loading

Load route components on demand with .lazy(). The function you pass should return a dynamic import:

const analytics = route("/analytics").lazy(() => import("./AnalyticsPage"));

The imported module should use a default export:

// AnalyticsPage.tsx
export default function AnalyticsPage() { ... }

If you're using a named export, you need to explicitly select which component to use by chaining .then() on the import:

const analytics = route("/analytics").lazy(() =>
  import("./AnalyticsPage").then(m => m.AnalyticsPage)
);
 
// AnalyticsPage.tsx
export function AnalyticsPage() { ... }

Lazy routes work like any other route. Child routes inherit the parent's lazy-loaded components:

const dashboard = route("/dashboard").lazy(() => import("./Dashboard"));
const settings = dashboard.route("/settings").component(Settings);

When navigating to /dashboard/settings, React loads the dashboard component first, then renders settings inside it. The Dashboard component must include an <Outlet /> for the child route to appear.

See Route preloading for ways to load these components before the user navigates.

Data preloading

Use .preload() to run logic before navigation occurs, typically to prefetch data. Preload functions receive the target route's typed params and search values:

const userProfile = route("/users/:id")
  .search(z.object({ tab: z.enum(["posts", "comments"]).catch("posts") }))
  .preload(async ({ params, search }) => {
    await queryClient.prefetchQuery({
      queryKey: ["user", params.id, search.tab],
      queryFn: () => fetchUser(params.id, search.tab)
    });
  })
  .component(UserProfile);

See Route preloading for how to trigger preload functions.

Depending on when and how preloading is triggered, these functions may run repeatedly. Waymark intentionally doesn't cache or deduplicate the calls - that's the job of your data layer. Libraries like TanStack Query, SWR, or Apollo handle this well. For example, TanStack Query's staleTime prevents refetches when data is still fresh:

await queryClient.prefetchQuery({
  queryKey: ["user", params.id],
  queryFn: () => fetchUser(params.id),
  staleTime: 60_000 // No refetch within 60s
});

Preload functions inherit to child routes:

const dashboard = route("/dashboard")
  .preload(prefetchDashboardData)
  .component(DashboardLayout);
 
const settings = dashboard.route("/settings").component(Settings);
// Preloading /dashboard/settings runs prefetchDashboardData

Error boundaries

Catch errors thrown during rendering with .error(). The error component receives the error as a prop:

const fragile = route("/fragile").error(ErrorFallback).component(FragilePage);
 
function ErrorFallback({ error }: { error: unknown }) {
  return (
    <div>
      <h2>Something went wrong</h2>
      <pre>{String(error)}</pre>
      <button onClick={() => window.location.reload()}>Retry</button>
    </div>
  );
}

Error boundaries catch errors from all nested content. A common pattern is to place one at the root to catch any unhandled errors:

const app = route("/").error(ErrorPage).component(AppLayout);

To give new routes a fresh start, the error boundary automatically resets when navigation occurs.

Suspense boundaries

When using lazy loading or React's use() hook for data fetching, you may want to add suspense boundaries to show loading states. Add them with .suspense():

const dataPage = route("/data")
  .suspense(LoadingPage)
  .lazy(() => import("./DataPage"));
 
function LoadingPage() {
  return <div>Loading...</div>;
}

The suspense boundary wraps everything below it in the route tree. Place it strategically to control which parts of the UI show a loading state.

You can combine suspense with error boundaries:

const riskyPage = route("/risky")
  .error(ErrorFallback)
  .suspense(Loading)
  .lazy(() => import("./RiskyPage"));

Note: React 19 has a known throttling behavior where suspense fallback hiding is delayed by up to 300ms. This can make fast-loading content feel slower than it is. Keep this in mind when designing loading experiences.

Route handles

Handles let you attach static arbitrary metadata to routes. This is useful for breadcrumbs, page titles, access control flags, or any other static data you want to associate with a route.

Define handles with .handle():

const dashboard = route("/dashboard")
  .handle({ title: "Dashboard", requiresAuth: true })
  .component(DashboardPage);
 
const settings = dashboard
  .route("/settings")
  .handle({ title: "Settings" })
  .component(SettingsPage);

Access all handles from the current route chain with useHandles(). It returns an array of all handles from the root down to the current matching route. This hook can be called from anywhere inside the route tree:

function Breadcrumbs() {
  const handles = useHandles();
  return (
    <nav>
      {handles.map((h, i) => (
        <span key={i}>
          {i !== 0 && " / "}
          {h.title}
        </span>
      ))}
    </nav>
  );
}

On /dashboard/settings, this renders "Dashboard / Settings". You can place the Breadcrumbs component anywhere in your app layout, and it will always reflect the current route's handle chain.

For type safety, register your handle type in the module augmentation:

declare module "waymark" {
  interface Register {
    routes: typeof routes;
    handle: { title: string; requiresAuth?: boolean };
  }
}

Route matching and ranking

When a user navigates to a URL, Waymark needs to determine which route matches. Since multiple routes can potentially match the same path (think /users/:id vs /users/new), Waymark uses a ranking algorithm to pick the most specific one.

Each segment in a route pattern gets a weight:

Segment type	Weight	Example
Static	2	`users`, `settings`, `new`
Dynamic	1	`:id`, `:slug?`
Wildcard	0	``, `?`

When multiple routes match, Waymark compares them segment by segment from left to right. The route with the higher weight at the first differing position wins. If weights are equal, it continues to the next segment.

Consider these routes:

const userNew = route("/users/new").component(NewUser);
const userProfile = route("/users/:id").component(UserProfile);
const userCatchAll = route("/users/*").component(UserCatchAll);

For the path /users/new, all three would match. Waymark ranks them to pick the most specific:

/users/new  → [static, static]   → weights [2, 2] ✓ Wins
/users/:id  → [static, dynamic]  → weights [2, 1]
/users/*    → [static, wildcard] → weights [2, 0]

The first segment (users) is static in all routes, so they all score 2 there. The second segment differs: new is static (2), :id is dynamic (1), and * is a wildcard (0). So /users/new wins.

For the path /users/42:

/users/new  → doesn't match
/users/:id  → [static, dynamic]  → weights [2, 1] ✓ Wins
/users/*    → [static, wildcard] → weights [2, 0]

This ranking algorithm means you don't need to order your routes array carefully. Define them in any order and Waymark figures out the right match regardless:

const routes = [
  route("/posts/*").component(NotFound),
  route("/posts/:id").component(PostPage),
  route("/posts/new").component(NewPost)
]; // Order doesn't matter

History implementations

History is an abstraction layer that sits between the router and the actual low-level navigation logic. It handles reading and updating the current location, managing navigation state, and notifying when the URL changes. This abstraction allows Waymark to work in different environments (browser, hash-based, in-memory, server-side, tests, etc.) without changing the router's core logic. You can switch between environments simply by swapping the history implementation - the rest of your app stays exactly the same.

Waymark supports three history modes out of the box.

BrowserHistory is the default. It uses the browser's History API, working with browser URLs like /posts/123:

import { BrowserHistory } from "waymark";
 
<RouterRoot routes={routes} history={new BrowserHistory()} />;

HashHistory stores the path in the URL hash, producing URLs like /#/posts/123. This is useful for static file hosting where you can't configure server-side routing:

import { HashHistory } from "waymark";
 
<RouterRoot routes={routes} history={new HashHistory()} />;

MemoryHistory keeps the history in memory without touching the URL. It also doesn't rely on any browser API. Perfect for testing, server-side rendering (SSR), or embedded applications:

import { MemoryHistory } from "waymark";
 
<RouterRoot routes={routes} history={new MemoryHistory("/initial/path")} />;

All history implementations conform to the HistoryLike interface, so you can create custom implementations if needed.

Cookbook

Quick start example

Here's a minimal but complete routing setup with a layout and two pages:

import { route, RouterRoot, Outlet, Link } from "waymark";
 
// Layout route
const app = route("/").component(AppLayout);
 
function AppLayout() {
  return (
    <div>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/about">About</Link>
      </nav>
      <main>
        <Outlet />
      </main>
    </div>
  );
}
 
// Page routes
const home = app.route("/").component(() => <h1>Welcome home</h1>);
const about = app.route("/about").component(() => <h1>About us</h1>);
 
// Router setup
const routes = [home, about];
 
export function App() {
  return <RouterRoot routes={routes} />;
}
 
declare module "waymark" {
  interface Register {
    routes: typeof routes;
  }
}

Server-side rendering (SSR)

Waymark supports server-side rendering using MemoryHistory. The key is to use MemoryHistory on the server (initialized with the request URL) and BrowserHistory on the client:

// server.tsx
import { renderToString } from "react-dom/server";
import { RouterRoot, MemoryHistory, type SSRContext } from "waymark";
import { routes } from "./routes";
 
function handleRequest(req: Request) {
  const ssrContext: SSRContext = {};
  const html = renderToString(
    <RouterRoot
      routes={routes}
      history={new MemoryHistory(req.url)}
      ssrContext={ssrContext}
    />
  );
  if (ssrContext.redirect) {
    return Response.redirect(ssrContext.redirect);
  }
  return new Response(html, {
    headers: { "Content-Type": "text/html" }
  });
}

The ssrContext object captures information during server rendering. When a Navigate component renders on the server (typically from conditional logic), it populates ssrContext.redirect with the target URL. Your server can then return an HTTP redirect instead of the rendered HTML.

On the client, use the default (BrowserHistory) for hydration:

// client.tsx
import { hydrateRoot } from "react-dom/client";
import { RouterRoot } from "waymark";
import { routes } from "./routes";
 
hydrateRoot(rootElement, <RouterRoot routes={routes} />);

You can also manually set ssrContext.statusCode in your components during SSR to control the response status (like 404 for not found pages).

Scroll to top on navigation

Create a component that scrolls to top when the path changes and include it in your layout:

import { useLocation } from "waymark";
import { useEffect } from "react";
 
function ScrollToTop() {
  const { path } = useLocation();
  useEffect(() => window.scrollTo(0, 0), [path]);
  return null;
}
 
function AppLayout() {
  return (
    <>
      <ScrollToTop />
      <Header />
      <Outlet />
    </>
  );
}

Matching a route anywhere

Use useMatch to check if a route matches the current path from anywhere in your component tree. You can pass either a route pattern string or a route object, just like with Link and navigate. This is useful for conditional rendering, styling, access control, and more. It's also used internally by useParams and Link.

By default, useMatch uses loose matching where the current path only needs to start with the route's path. To require an exact match instead, pass strict: true:

import { useMatch } from "waymark";
 
const dashboard = route("/dashboard").component(Dashboard);
const settings = route("/settings").component(Settings);
 
function Sidebar() {
  // Loose matching: matches /dashboard and /dashboard/literally/anything
  const dashboardMatch = useMatch({ from: "/dashboard" });
 
  // Strict matching: matches only /settings
  const settingsMatch = useMatch({ from: settings, strict: true });
 
  return (
    <nav>
      {dashboardMatch && <DashboardMenu />}
      {settingsMatch && <SettingsSubmenu />}
    </nav>
  );
}

You can also filter by param values to match only specific instances:

const adminMatch = useMatch({
  from: "/users/:id",
  params: { id: "admin" }
});
 
if (adminMatch) {
  // Currently viewing the admin user
}

Global link configuration

Set defaults for all Link components using defaultLinkOptions on the router. Useful for consistent styling and preload behavior across your app:

<RouterRoot
  routes={routes}
  defaultLinkOptions={{
    preload: "intent",
    preloadDelay: 75,
    className: "app-link",
    activeClassName: "active"
  }}
/>

Individual links can override any of these defaults by passing their own props.

History middleware

This is a design pattern rather than a feature. You can extend history behavior for logging, analytics, or other side effects by monkey-patching the history instance:

function withAnalytics(history: HistoryLike): HistoryLike {
  const { push } = history;
 
  history.push = options => {
    analytics.track("page_view", { url: options.url });
    push(options);
  };
 
  return history;
}
 
function withLogging(history: HistoryLike): HistoryLike {
  const { go, push } = history;
 
  history.go = delta => {
    console.log("Navigate", delta > 0 ? "forward" : "back");
    go(delta);
  };
 
  history.push = options => {
    console.log("Navigate to", options.url);
    push(options);
  };
 
  return history;
}
 
// Compose middlewares
const router = new Router({
  routes,
  history: withLogging(withAnalytics(new BrowserHistory()))
});

View transitions

You can use the view transitions API for smoother page animations. Create a history middleware that wraps navigation in a view transition:

import { flushSync } from "react-dom";
import { BrowserHistory, type HistoryLike } from "waymark";
 
const withViewTransition = (history: HistoryLike) => {
  const { go, push } = history;
 
  const wrap = (fn: () => void) => {
    return !document.startViewTransition
      ? fn()
      : document.startViewTransition(() => flushSync(fn));
  };
 
  history.go = delta => wrap(() => go(delta));
  history.push = options => wrap(() => push(options));
  return history;
};
 
const history = withViewTransition(new BrowserHistory());
 
function App() {
  return <RouterRoot routes={routes} history={history} />;
}

Add CSS to control the transition:

::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 200ms;
}

For more advanced techniques, see the MDN documentation on View Transitions.

API reference

Router class

The Router class is the core of Waymark. You can create an instance directly or let RouterRoot create one.

Properties:

router.basePath - The configured base path
router.routes - The array of routes
router.history - The history instance
router.ssrContext - The SSR context (if provided)
router.defaultLinkOptions - Default link options

new Router(options) creates a new router.

options - RouterOptions - Router configuration
Returns: Router - A new router instance

const router = new Router({ routes });
const router = new Router({ routes, basePath: "/app" });
const router = new Router({ routes, history: new HashHistory() });

router.navigate(options) navigates to a new location.

options - NavigateOptions | HistoryPushOptions | number - Type-safe navigation options, untyped navigation options, or a history delta
Returns: void

// Type-safe navigation
router.navigate({ to: "/posts/:id", params: { id: "42" } });
 
// Untyped navigation
router.navigate({ url: "/any/path" });
 
// History navigation
router.navigate(-1); // Back
router.navigate(1); // Forward

router.createUrl(options) builds a URL string.

options - NavigateOptions - Type-safe navigation options
Returns: string - The constructed URL

const url = router.createUrl({ to: userProfile, params: { id: "42" } });
// Returns "/users/42"

router.match(path, options) checks if a path matches a specific route.

path - string - The path to match against
options - MatchOptions - Matching options
Returns: Match | null - The match result or null if no match

const match = router.match("/users/42", { from: "/users/:id" });
// Returns { route, params: { id: "42" } } or null

router.matchAll(path) finds the best match from all registered routes.

path - string - The path to match against
Returns: Match | null - The best match or null if no route matches

const match = router.matchAll("/users/42");
// Returns the best match or null

router.getRoute(pattern) get a route by its pattern.

pattern - Pattern | Route - A route pattern string or a route object
Returns: Route - The route object; throws if not found

const route = router.getRoute("/users/:id");

router.preload(options) triggers preloading for a route.

options - NavigateOptions - Type-safe navigation options
Returns: Promise<void> - Resolves when preloaded

await router.preload({ to: "/user/:id", params: { id: "42" } });
await router.preload({ to: searchPage, search: { q: "test" } });

Route class

Routes are created with the route() function and configured by chaining methods.

route(pattern) creates a new route.

pattern - string - The route path pattern (e.g., "/users", "/users/:id", "/*")
Returns: Route - A new route object

const users = route("/users");
const user = route("/users/:id");
const catchAll = route("/*");

.route(pattern) creates a nested child route.

pattern - string - The child path pattern to append
Returns: Route - A new route object

const userSettings = user.route("/settings");
// Pattern becomes "/users/:id/settings"

.component(component) adds a component to render when this route matches.

component - ComponentType - A React component
Returns: Route - A new route object

const users = route("/users").component(UsersPage);

.lazy(loader) adds a lazy-loaded component to render when this route matches.

loader - ComponentLoader - A function returning a dynamic import promise
Returns: Route - A new route object

const users = route("/users").lazy(() => import("./UsersPage"));
const admin = route("/admin").lazy(() =>
  import("./Admin").then(m => m.AdminPage)
);

.search(validate) adds search parameter validation.

validate - StandardSchema | ((search) => ValidatedSearch) - A Standard Schema (like Zod) or a validation function
Returns: Route - A new route object

const search = route("/search").search(z.object({ q: z.string() }));
const filter = route("/filter").search(raw => ({
  term: String(raw.term ?? "")
}));

.handle(handle) attaches static metadata to the route.

handle - Handle - Arbitrary metadata
Returns: Route - A new route object

const admin = route("/admin").handle({ requiresAuth: true });

.suspense(fallback) wraps nested content in a Suspense boundary.

fallback - ComponentType - The fallback component to show while suspended
Returns: Route - A new route object

const lazy = route("/lazy")
  .suspense(Loading)
  .lazy(() => import("./Page"));

.error(fallback) wraps nested content in an error boundary.

fallback - ComponentType<{ error: unknown }> - The fallback component, receives the caught error as a prop
Returns: Route - A new route object

const risky = route("/risky").error(ErrorPage).component(RiskyPage);

.preload(preload) registers a preload function for the route.

preload - (context: PreloadContext) => Promise<any> - An async function receiving typed params and search
Returns: Route - A new route object

const user = route("/users/:id")
  .search(z.object({ tab: z.string().catch("profile") }))
  .preload(async ({ params, search }) => {
    // params.id: string, search.tab: string - fully typed
    await prefetchUser(params.id, search.tab);
  });

Hooks

useRouter() returns the Router instance from context.

Returns: Router - The router instance

const router = useRouter();

useNavigate() returns a navigation function.

Returns: (options: NavigateOptions | HistoryPushOptions | number) => void - The navigate function

const navigate = useNavigate();
navigate({ to: "/home" });
navigate(-1);

useLocation() returns the current location, subscribes to changes.

Returns: { path: string, search: Record<string, unknown>, state: any } - The current path, parsed search params, and history state

const { path, search, state } = useLocation();

useOutlet() returns the child route content.

Returns: ReactNode - The child route's content or null

const outlet = useOutlet();

useParams(route) returns typed path params for a route.

route - Pattern | Route - A route pattern string or route object
Returns: Params - The extracted path params, fully typed

const { id } = useParams(userRoute);

useSearch(route) returns validated search params and a setter function.

route - Pattern | Route - A route pattern string or route object
Returns: [Search, SetSearch] - A tuple of the validated search params and a setter; the setter accepts a partial update or an updater function, with an optional second argument to replace instead of push

const [search, setSearch] = useSearch(searchRoute);
setSearch({ page: 2 });
setSearch(prev => ({ page: prev.page + 1 }));
setSearch({ page: 1 }, true); // Replace instead of push

useMatch(options) checks if a route matches the current path.

options - MatchOptions - Matching options
Returns: Match | null - The match result or null if no match

const match = useMatch({ from: "/users/:id" });
const strictMatch = useMatch({ from: "/users", strict: true });
const filteredMatch = useMatch({ from: "/users/:id", params: { id: "admin" } });

useHandles() returns the handles from the matched route chain.

Returns: Handle[] - Array of handles

const handles = useHandles();

Components

RouterRoot sets up routing context and renders your routes.

props - RouterOptions | { router: Router } - Either router options (same as the Router constructor) or a router instance

<RouterRoot routes={routes} basePath="/app" history={history} />
<RouterRoot router={router} />

Outlet renders the child route content.

function Layout() {
  return (
    <div>
      <Outlet />
    </div>
  );
}

Link renders an anchor tag for navigation.

props - NavigateOptions & LinkOptions & { asChild?: boolean } - Navigation options, link options, and optional asChild to use a child element as the anchor; other props are passed through

<Link to="/path" params={...} search={...} replace strict preload="intent">
  Click me
</Link>

Navigate redirects on render.

props - NavigateOptions - The navigation target

<Navigate to="/login" replace />

History interface

The HistoryLike interface defines how Waymark interacts with navigation. All history implementations conform to this interface.

Available implementations:

new BrowserHistory(); // Browser History API (/posts/123). Default.
new HashHistory(); // URL hash (/#/posts/123).
new MemoryHistory("/initial"); // In-memory only.

See History implementations for detailed usage.

history.getPath() returns the current path.

Returns: string - The current path

const path = history.getPath();
// Returns "/users/42"

history.getSearch() returns the current search params as a parsed JSON object.

Returns: Record<string, unknown> - The parsed search params

const search = history.getSearch();
// Returns { tab: "posts", page: 2 }

history.getState() returns the current history state.

Returns: any - The state passed during navigation, or undefined

const state = history.getState();
// Returns any state passed during navigation

history.go(delta) navigates forward or back in history.

delta - number - The number of entries to move
Returns: void

history.go(-1); // Go back
history.go(1); // Go forward
history.go(-2); // Go back two steps

history.push(options) pushes or replaces a history entry.

options - HistoryPushOptions - The URL to navigate to, with optional replace and state
Returns: void

history.push({ url: "/users/42", state: { from: "list" } });
history.push({ url: "/login", replace: true });

history.subscribe(listener) subscribes to navigation events.

listener - () => void - Callback invoked when any navigation occurs
Returns: () => void - An unsubscribe function

const unsubscribe = history.subscribe(() => {
  console.log("Navigation occurred");
});
 
// Later: unsubscribe()

Types

RouterOptions are options for creating a Router instance or passing to RouterRoot.

interface RouterOptions {
  routes: Route[]; // Array of navigable routes (required)
  basePath?: string; // Base path prefix (default: "/")
  history?: HistoryLike; // History implementation (default: BrowserHistory)
  ssrContext?: SSRContext; // Context for server-side rendering
  defaultLinkOptions?: LinkOptions; // Default options for all Link components
}

NavigateOptions are options for type-safe navigation.

type NavigateOptions = {
  to: Pattern | Route; // Route pattern string or route object
  params?: Params; // Path params
  search?: Search; // Search params
  replace?: boolean; // Replace history entry instead of pushing
  state?: any; // Arbitrary state to pass
};

HistoryPushOptions are options for untyped navigation.

interface HistoryPushOptions {
  url: string; // The URL to navigate to
  replace?: boolean; // Replace history entry instead of pushing
  state?: any; // Arbitrary state to pass
}

MatchOptions are options for route matching.

type MatchOptions = {
  from: Pattern | Route; // The route to match against
  strict?: boolean; // Require exact match (default: false, matches prefixes)
  params?: Partial<Params>; // Optional param values to filter by
};

Match is the result of a successful route match.

type Match = {
  route: Route; // Matched route object
  params: Params; // Extracted path params
};

LinkOptions controls link behavior and styling.

interface LinkOptions {
  strict?: boolean; // Strict matching for active state detection
  preload?: "intent" | "render" | "viewport" | false; // When to trigger preloading
  preloadDelay?: number; // Delay in ms before preloading starts (default: 50)
  style?: CSSProperties; // Base styles for the link
  className?: string; // Base class name for the link
  activeStyle?: CSSProperties; // Additional styles when active
  activeClassName?: string; // Additional class name when active
}

SSRContext captures context during server-side rendering.

type SSRContext = {
  redirect?: string; // Set by Navigate component during SSR
  statusCode?: number; // Can be set manually for HTTP status
};

PreloadContext is the context passed to preload functions.

interface PreloadContext {
  params: Params; // Path params for the route
  search: Search; // Validated search params
}

Roadmap

Possibility to pass an arbitrary context to the Router instance for later use in preloads?
Relative path navigation? Not sure it's indispensable given that users can export/import route objects and pass them as navigation option.
Document usage in test environments
Devtools? Let me know if needed.
Open to suggestions, we can discuss them here.

License

MIT