Skip to content

Getting Started

Build a two-page lesson notebook whose links change the URL without replacing the document. A route connects a pathname pattern to a React component; the router matches the current location and renders that component.

This walkthrough uses the React entry point, @studiolambda/router/react. If you only need to match pathnames, the framework-independent matcher needs no React installation.

Use Node.js 22.12 or newer, npm, and a browser with the Navigation API. The React integration requires React and React DOM 19.2 or newer within the 19.x peer range. It uses native navigation interception, not a History API fallback.

In a terminal, create a Vite React/TypeScript project:

Terminal window
npm create vite@latest lesson-notebook -- --template react-ts
cd lesson-notebook
npm install
npm install @studiolambda/router react@^19.2.0 react-dom@^19.2.0 react-error-boundary

Vite supplies index.html, TypeScript configuration, and the development server. Keep those generated files. Replace the two application files below; no API server, account, or data service is needed.

Replace src/App.tsx with:

import { ErrorBoundary } from 'react-error-boundary'
import {
createRouter,
Link,
Router,
useParams,
type MiddlewareProps,
} from '@studiolambda/router/react'
function Layout({ children }: MiddlewareProps) {
return (
<>
<nav aria-label="Main">
<Link href="/">Notebook</Link>{' '}
<Link href="/lessons/routing">Routing lesson</Link>
</nav>
<main>{children}</main>
</>
)
}
function Home() {
return (
<>
<h1>Lesson notebook</h1>
<p>Choose a lesson to begin.</p>
<Link href="/lessons/routing">Read about routing</Link>
</>
)
}
function Lesson() {
const { slug } = useParams()
return <h1>Lesson: {slug}</h1>
}
function MissingPage() {
return (
<main>
<h1>Lesson not found</h1>
<Link href="/">Return to the notebook</Link>
</main>
)
}
export const matcher = createRouter((route) => {
const pages = route().middleware([Layout]).group()
pages('/').render(Home)
pages('/lessons/:slug').render(Lesson)
})
export default function App() {
return (
<ErrorBoundary fallback={<p>Could not open the notebook. Reload to retry.</p>}>
<Router
matcher={matcher}
notFound={MissingPage}
fallback={<p>Opening lesson…</p>}
onNavigateError={(error) => console.error('navigation failed', error)}
/>
</ErrorBoundary>
)
}

createRouter builds the route table once, outside component rendering. :slug captures one pathname segment, so /lessons/routing renders Lesson with slug equal to 'routing'. Parameters are strings, not validated domain values.

The pathless group applies Layout to both registered pages. This wrapper is called middleware: a React component that receives the matched page as children. It puts the navigation inside the router’s providers, where Link can read active-route state. Router itself does not accept children.

An unmatched URL uses MissingPage instead. That fallback is not part of the group, so it supplies its own structure. The error boundary handles render failures; onNavigateError observes failed native navigations. These are different failure paths.

Replace src/main.tsx with:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App'
const container = document.getElementById('root')
if (container === null) throw new Error('root element is missing')
const root = createRoot(container)
root.render(
'navigation' in window ? (
<StrictMode>
<App />
</StrictMode>
) : (
<p>This application needs a browser with Navigation API support.</p>
),
)

This capability check gives unsupported browsers an explicit message. Without a navigation prop, context provider, or window.navigation, Router throws. The memory adapter is for a fixed server/test location; it does not add browser navigation support.

Start Vite from lesson-notebook:

Terminal window
npm run dev -- --host localhost --port 5173

Open http://localhost:5173/. You should see Lesson notebook and the shared navigation. Select Read about routing: the URL becomes /lessons/routing and the heading becomes Lesson: routing. Browser Back returns to the notebook. Open /missing to see Lesson not found, then use its return link.

The development server can serve the app for direct route URLs. Your production host needs the equivalent document fallback configuration. Stop the local server with Ctrl+C when finished.

Learn how patterns choose a match before adding overlapping routes. Then use route groups and layouts to grow the notebook without duplicating setup.

Later guides use focused fragments: application-owned components or dependencies are named before the example rather than reprinting the whole app. Complete files are labeled explicitly. Imports come from the released package, not a repository checkout.