Skip to content

Defining Routes

As your application grows, related URLs often need the same layout or access check. A group creates a scoped route factory: child routes inherit selected configuration and, optionally, a pathname prefix. It does not render a parent page or create an outlet.

Start with a mounted quickstart application. The examples below use createRouter, useParams, and the exported RouteFactory type from @studiolambda/router/react; named page components stand for your own existing components.

To make an existing LessonPage available at a URL, create its builder and finish with render:

import { createRouter } from '@studiolambda/router/react'
import LessonPage from './LessonPage'
export const matcher = createRouter((route) => {
route('/lessons/:slug').render(LessonPage)
})

Pass this matcher to <Router matcher={matcher} />. The route component receives no route props; it reads parameters and location through hooks. Create the table outside rendering so rerenders do not replace the matcher or its speculative-prefetch identity.

Each builder is single-use. Configuration methods return that builder; render, redirect, and group consume it. Calling any method afterward throws. Call the route factory again to create a sibling, rather than trying to reuse a consumed builder.

A URL is user input. The matcher determines which pattern fits, but it does not prove that a lesson exists or convert captures into numbers. In src/LessonPage.tsx, a complete page can validate a small supported set before rendering:

import { useParams } from '@studiolambda/router/react'
const titles = new Map([
['routing', 'Routing fundamentals'],
['navigation', 'Moving between pages'],
])
export default function LessonPage() {
const { slug } = useParams()
const title = titles.get(slug)
if (title === undefined) return <h1>Unknown lesson</h1>
return <h1>{title}</h1>
}

useParams() returns Record<string, string>, including wildcard captures. There is no route-name generic, typed href generator, schema validator, or automatic decoding. Treat the shared record as read-only and validate the actual value before using it in consequential application code. A valid pathname with an unknown lesson is still a matched route; the router’s notFound component is only for unmatched paths.

With existing LessonIndex and LessonPage components, group them under /lessons:

const matcher = createRouter((route) => {
const lessons = route('/lessons').group()
lessons('/').render(LessonIndex)
lessons('/:slug').render(LessonPage)
})

The resulting paths are /lessons and /lessons/:slug. lessons().render(LessonIndex) also registers the group root, since the prefix supplies its path. At the top level, route().render(...) has neither path nor prefix and throws.

Groups can nest, accumulating prefixes. A child starting with / still appends to its group; it does not escape to the application root. Use the outer route factory for an unrelated absolute route. Use a pathless route().group() when you need shared configuration but no URL prefix.

SettingGroup behavior
PathPrefixes child paths
guard(fn)Appends checks; parent checks run first
prefetch(fn)Appends callbacks; parent callbacks run first, sequentially
middleware([Component])Appends wrappers; parent wrappers are outermost
scroll(behavior)Route-local; not inherited
focusReset(behavior)Route-local; not inherited
formHandler(fn)Route-local; not inherited

Configuration flows down, not sideways. Adding middleware to one child does not change its siblings. Repeated guard, prefetch, and middleware calls append; repeated scroll, focus-reset, or form-handler calls replace the local value.

Select the mechanism by responsibility: guards enforce mandatory checks, prefetch warms resources, and middleware wraps rendered UI. All guards finish before the prefetch chain begins; the operations are not interleaved parent by parent.

When a feature owns several routes, pass it a scoped factory instead of sharing a mutable builder. A feature module can accept the exported type:

import { type RouteFactory } from '@studiolambda/router/react'
import LessonPage from './LessonPage'
export function registerLessons(route: RouteFactory) {
route('/:slug').render(LessonPage)
}

In your route-table module, import registerLessons and call registerLessons(route('/lessons').group()) inside createRouter. The feature’s /:slug becomes /lessons/:slug, and inherited guards/layouts still apply. Choose one owner for each path to avoid duplicate registrations.

The browser normally manages scrolling and focus after its navigation handler completes. Keep those defaults unless an editor, virtualized list, or similar screen deliberately manages them:

route('/editor')
.scroll('manual')
.focusReset('manual')
.render(EditorPage)

Here route is the factory inside your existing createRouter callback, and EditorPage is your component. Both options accept 'after-transition' or 'manual'. Manual mode disables the browser’s corresponding automatic behavior; you must provide an accessible replacement. These options are passed to native interception, not to the component as props.

createRouter returns Matcher<Handler>. If an integration needs direct registration, import createMatcher from @studiolambda/router and Handler from the React entry point; register an object with the required component plus optional guard, prefetch, middlewares, scroll, focusReset, and formHandler. The builder remains the ordinary choice because it composes inheritance and checks static redirect cycles for you.