Quickstart

This is the shortest path to a routekit app. By the end you’ll have a single-page app that routes between three pages, lazy-loads each, and is fully typed.

1. Install the package.

   npm install routekit

2. Define your routes. A route is a path and a handler. The handler is any async function — typically () => import(...) for code-splitting.

   src/routes.ts

   export const routes = [
     { path: '/',           handler: () => import('./pages/home') },
     { path: '/posts',      handler: () => import('./pages/posts') },
     { path: '/posts/:id',  handler: () => import('./pages/post') },
   ] as const;

   The as const is what gives you type-safe params — see TypeScript usage.

3. Mount the router.

   src/main.ts

   import { createRouter } from 'routekit';
   import { routes } from './routes';
   
   const router = createRouter(routes);
   
   router.on('navigate', async ({ match }) => {
     const { default: render } = await match.handler();
     render(document.querySelector('#app')!, match.params);
   });
   
   router.start();

4. Build a page handler. Each route module exports a default render function. routekit doesn’t care what’s inside — it only calls the function.

   src/pages/post.ts

   export default function render(root: HTMLElement, params: { id: string }) {
     root.innerHTML = `<h1>Post #${params.id}</h1>`;
   }

5. Run it. Use any dev server (Vite, esbuild, Bun, plain http-server). Navigate to /posts/42 and the post page will render.

Note

routekit doesn’t ship a build step or a dev server. Use what you already use. The library is ~3 KB and works with any toolchain that bundles ESM.

What just happened

The first time you visit /posts/42:

1. The browser fires a navigation event when router.start() reads window.location.
2. routekit matches /posts/42 against the route table → finds /posts/:id → extracts { id: '42' }.
3. The match is delivered to your 'navigate' handler.
4. Your handler calls match.handler() — which lazy-imports ./pages/post — and renders into #app.

Everything after this is just iterating: more routes, nested layouts (see navigation), code-split chunks (see code splitting).

Next: your first route

Walk through building a real route from scratch, with type-safe params and an active-link styling helper.