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
npm install @k8ordo/routerIt 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.tsimport { 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.tsximport { 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.
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.
Links
src/pages/product-list.tsximport { 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.tsximport { 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.