@k8ordo/router

Get Started

The example is a Vite and React shop with a product list and a page per product. Write a route table, render it in the browser, and link the pages together.

On this page

Install

bash
npm install @k8ordo/router

It runs with:

  • React 19.3 or later
  • TypeScript 7 or later, when you write TypeScript

The guide for AI agents ships at node_modules/@k8ordo/router/docs/GUIDE.md. Point your AGENTS.md or the like at that path.

Navigation goes through the browser's Navigation API and matching through URLPattern. There is no polyfill and no fallback.

Defining the route table

src/routes.ts
import { defineRoutes } from '@k8ordo/router';

import { Home } from './pages/home';
import { NotFound } from './pages/not-found';
import { ProductList } from './pages/product-list';
import { ProductPage } from './pages/product-page';

export const routes = defineRoutes({
  '/': Home,
  '/products': ProductList,
  '/products/:id': ProductPage,
`:id` is a param that takes one segment of the path
  '/*': NotFound,
Takes any path no pattern above it matched
});

List each path the app serves and the page shown there in defineRoutes. A key is a path pattern, and its value is the page component. A page is a React component that takes no props.

At /products/42, ProductPage is shown and id is '42'. Patterns are tried from the top down, so /* goes last.

Moving between pages keeps layouts mounted and swaps only what is inside <Outlet />. Layouts and route groups are covered in Route table.

Mounting the router

src/main.tsx
import { Router } from '@k8ordo/router';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';

import { routes } from './routes';

const root = document.querySelector('#root');
if (root === null) throw new Error('#root is missing');

createRoot(root).render(
  <StrictMode>
    <Router routes={routes} />
  </StrictMode>,
);

Render <Router> at the top of the app and hand it the route table. It matches the browser's current path against the table and shows the matching page.

Information

Note

<Router> is for an app that renders in the browser. To render on a server or generate pages at build time, use @k8ordo/framework.

src/pages/product-list.tsx
import { href } from '@k8ordo/router';

const products = [
  { id: '1', name: 'Desk lamp' },
  { id: '2', name: 'Notebook' },
];

export function ProductList() {
  return (
    <ul>
      {products.map((product) => (
        <li key={product.id}>
          <a href={href('/products/:id', { id: product.id })}>
Leaving out `id` is a type error
            {product.name}
          </a>
        </li>
      ))}
    </ul>
  );
}

Build a link target by handing href the pattern and its params. The param types are inferred from the pattern string.

A link is a plain <a>. <Router> intercepts the navigation the browser reports when it is followed, so the document is not reloaded.

Reading params

src/pages/product-page.tsx
import { href, useParams } from '@k8ordo/router';

export function ProductPage() {
  const { id } = useParams('/products/:id');
Reads the param by the page’s own pattern

  return (
    <article>
      <h1>Product {id}</h1>
      <a href={href('/products')}>Back to the list</a>
    </article>
  );
}

The page reads its params by handing useParams its own pattern. Neither file imports the route table.

To make a pattern the table lacks a type error too, register the route table on Register. See Typed paths.

k8ordo

React libraries that use Baseline features without holding back.