Getting Started

λ Router is a declarative router built on the browser’s native Navigation API. It uses a trie-based URL pattern matcher, a chainable builder API for defining routes, and React 19 features like useTransition and Suspense for concurrent rendering during navigations.

Installation

Install the @studiolambda/router package from NPM:

npm i @studiolambda/router

λ Router requires React 19 as a peer dependency.

Quick Start

A minimal application with λ Router involves three steps: defining your routes, creating your page components, and rendering the Router component.

import { createRouter, Router } from "@studiolambda/router/react";
import { createRoot } from "react-dom/client";

function Home() {
  return <h1>Home</h1>;
}

function About() {
  return <h1>About</h1>;
}

function App() {
  const router = createRouter(function (route) {
    route("/").render(Home);
    route("/about").render(About);
  });

  return <Router matcher={router} />;
}

createRoot(document.getElementById("root")!).render(<App />);

That’s it. The Router component listens to the browser’s Navigation API, matches the current URL against your routes, and renders the corresponding component inside a <Suspense> boundary. Navigations are wrapped in React transitions so your UI stays responsive throughout.

How It Works

When a user navigates (clicking a link, using the browser back/forward buttons, or calling navigation.navigate() programmatically), the browser fires a navigate event. λ Router intercepts this event and:

1. Matches the destination URL against your route patterns using a trie-based matcher.
2. Runs prefetch handlers (if any) during the precommit phase, before the URL bar updates. This is the ideal time to warm data caches.
3. Commits the URL — the browser’s address bar updates.
4. Renders the new component inside a React transition so the previous UI remains visible until the new one is ready.

This means navigations are non-blocking. If the new page suspends (e.g., while loading data), the old page stays on screen and a pending state is available for showing loading indicators.

Navigation API Support

λ Router is built on the Navigation API, which is supported in all Chromium-based browsers (Chrome, Edge, Opera, Arc, Brave, etc.). For browsers without support, the router provides createMemoryNavigation() for SSR and testing scenarios.

Next Steps

• Pattern Matching — Use the core URL matcher without React, in any JavaScript runtime.
• Defining Routes — Learn the builder API for route patterns, groups, and nesting.
• Components — The Router and Link components.
• Navigation — Programmatic navigation and URL management.
• Prefetching — Warm data caches during navigation.