Skip to content

Layouts and Middleware

Pages in the same part of an application often need the same navigation and frame. Middleware wraps a matched page in ordinary React components. It is render-time composition, not an HTTP request pipeline and not an access-control hook.

Use this page after defining your routes. Import MiddlewareProps, Link, and createRouter from @studiolambda/router/react for the examples below.

Router renders a registered component and has no children prop. A sibling navigation bar outside it does not automatically receive its contexts. Put your shared bar in a middleware component instead:

import { Link, type MiddlewareProps } from '@studiolambda/router/react'
export default function NotebookLayout({ children }: MiddlewareProps) {
return (
<>
<nav aria-label="Notebook">
<Link href="/">Home</Link>{' '}
<Link href="/lessons" activeExact={false}>Lessons</Link>
</nav>
<main>{children}</main>
</>
)
}

children is the next wrapper or the matched page. Render it where the page belongs. The layout can use router hooks because Router provides location, params, matcher, navigation, and transition contexts above the entire middleware chain.

In your existing route-table module, import NotebookLayout and attach it to a pathless group:

const matcher = createRouter((route) => {
const notebook = route().middleware([NotebookLayout]).group()
notebook('/').render(HomePage)
notebook('/lessons').render(LessonIndex)
notebook('/lessons/:slug').render(LessonPage)
})

Here HomePage, LessonIndex, and LessonPage are your existing pages. All three render inside the same frame. An unmatched path uses Router’s separate notFound component; it does not inherit this group. Give that component its own layout if it needs one.

If lesson pages also need a local sidebar, add a second middleware group beneath the notebook group. With an existing LessonLayout component accepting MiddlewareProps, use:

const matcher = createRouter((route) => {
const notebook = route().middleware([NotebookLayout]).group()
notebook('/').render(HomePage)
const lessons = notebook('/lessons').middleware([LessonLayout]).group()
lessons('/').render(LessonIndex)
lessons('/:slug').render(LessonPage)
})

The tree is NotebookLayout → LessonLayout → matched page. The first middleware in any array is outermost too: .middleware([A, B]) produces A around B, not the reverse. Multiple .middleware(...) calls append wrappers in call order.

This provides nested UI without nested route components or an outlet API. Only one complete route matches. The group does not first render a parent page and then ask that page to render a child route.

Middleware can supply an application context or place an error/Suspense boundary around its descendants. Import the actual provider from your application, wrap children, and attach that middleware before components that consume it. A provider inside middleware is available to later wrappers and pages, not to guards or prefetch callbacks: those execute outside React rendering.

The router’s own Suspense boundary wraps the middleware chain. If you want navigation to remain visible while a child suspends, put a more local Suspense boundary inside your layout around its children. Otherwise, an initial suspension can replace the entire layout with Router’s fallback. See loading and transitions.

React reconciles the wrapper tree as routes change. Do not treat middleware as a once-only initialization hook or promise that state survives every change in wrapper position/type. State that must outlive routes belongs in a stable application owner; state that must reset needs an explicit reset policy in your components.

A middleware can choose not to render children, but that decision is too late to gate route prefetch or form actions. Those operations may already have run. Use a mandatory guard when denial must stop dispatch before rendering, and authorize every backend request independently.

The exported Middlewares component is available for custom composition:

import { Middlewares } from '@studiolambda/router/react'
const content = (
<Middlewares value={[NotebookLayout, LessonLayout]}>
<LessonPage />
</Middlewares>
)

This fragment uses the components introduced above. An empty or undefined value leaves children unchanged. Middlewares adds no router providers, matching, checks, or navigation handling on its own; use Router for those responsibilities.