How to scope middleware errors to a layout boundary instead of root?

[VillePakarinenPosti]

I’d like some guidance on how to handle middleware in a way that keeps consistent user-experience across initial load and subsequent navigations with React Router ^7.8.1

I’m trying to guard everything under /edit/* so only privileged users can access those sub-routes, while keeping the main layout and navigation visible when access is denied.

Desired behavior

If a user without permissions navigates to /edit/operation-1 either on initial load or subsequent navigation, I’d like to throw from a guard (middleware) and have the parent layout’s error boundary render a friendly 403 message. Preserving the layout + nav rather than bubbling all the way to the root.

Why I’m asking

I want this to feel consistent on the initial load (all loaders run) and on client navigations (only affected loaders revalidate) without duplicating checks in every child route loader.

Minimal route structure (framework mode):

routes/
├── _layout.tsx                 # main layout (nav/shell)
├── home.tsx                    # /home
└── edit/                       # /edit/*
    ├── _layout.tsx             # layout that wraps edit routes, adds guard + scoped error boundary
    ├── operation-1.tsx         # /edit/operation-1
    └── operation-2.tsx         # /edit/operation-2

Reproduction: https://stackblitz.com/edit/github-zd8bdybn?file=app%2Froutes%2Fhome.tsx

Question

What’s the recommended approach to ensure a thrown 403 from a central guard for /edit/* is handled by the scoped error boundary so the nav/shell can remain visible and allows users to "navigate away"?

After thoughts

1. I was thinking that one option could be just to redirect the user to /permission-denied?from=/edit/..., but that breaks active-link matching (NavLink doesn’t highlight the intended section).
2. Root boundary could re-create the top level layout (now the layout becomes a bit obsolete)
3. Duplicating throws in every /edit/* child works but defeats the purpose of centralizing the guard.

[brophdawg11]

You won't be able to do this in pure SPA mode based on the underlying architecture of a SPA. The index.html used for SPA mode only renders the root route, and all other routes are lazily loaded via route.lazy. By throwing in a middleware before calling next, those routes are never loaded so the router has no idea that the edit/layout route has an error boundary so it has no choice but to bubble to the root route on initial load.

const middlewareThatThrows: unstable_MiddlewareFunction<undefined> = async (
  _args,
  next
) => {
  throw new Error("permission denied");

  // This is what runs route.lazy for the matched routes and loads their implementations
  // await next()
};

Throwing that error from a clientLoader works as expected because it has had a chance to load the layout route implementation and now knows about the ErrorBoundary, but that means the other matched route loaders will run as well so you would need to be ok with that or also be checking/short circuiting from them as well.

To do what you are looking for with middleware you need to go beyond a true SPA and start pre-rendering some pages specific to the edit route so you can get the layout route script in the initial HTML so it doesn't need to load via route.lazy.

Change it to a route:

export default [
  layout("routes/layout.tsx", [
    index("routes/home.tsx"),
    route("edit", "routes/edit/layout.tsx", [
      route("operation-1", "routes/edit/operation-1.tsx"),
      route("operation-2", "routes/edit/operation-2.tsx"),
    ]),
  ]),
] satisfies RouteConfig;

Then prerender the edit route:

export default {
  // Config options...
  // Server-side render by default, to enable SPA mode set this to `false`
  ssr: false,
  prerender: ["/edit"],
} satisfies Config;

Then you'll end up with build/client/edit?index.html and you will need custom server logic to tell any edit/* paths to use that, and then anything else should use build/client/index.html (the true SPA fallback).

Then, if you use redirectDocument in your / clientLoader to force a hard reload of the new URL it should work as expected since it'll load the edit/index.html file which will have the ErrorBoundary available.

[brophdawg11]

Is that a valid alternative, or are there other caveats I should keep in mind?

I think that would "work" but you'd be giving up all of the benefits of framework mode (type safety, code splitting, route modules, etc) and shipping a huge bundle up front which would likely slow down the loading speeds for your app.

it would be ran after the matched routes route.lazy has resolved

This is not an option because we'd resolve lazy for a bunch of routes we may not need because middlewares might redirect away from them, so it would be wasted.

[VillePakarinenPosti]

This is not an option because we'd resolve lazy for a bunch of routes we may not need because middlewares might redirect away from them, so it would be wasted.

I’ve been using selective route.lazy in the past together with patchRoutesOnNavigation when working in data mode. I’ve found both of these APIs really powerful for optimizing pure SPA applications with selective trade-offs.

Do you see framework mode ever supporting this type of decisions, (perhaps with some bundler-level magic) to allow more control over when and which parts of route modules are resolved up-front vs lazily?

[VillePakarinenPosti]

I created another small example with data mode in combination with middleware:
👉 https://codesandbox.io/p/devbox/data-router-middleware-demo-forked-p98cwd?workspaceId=ws_59aTLwQUBcb9VF2Fg2btyq

In this setup the middleware behaves exactly as I expected. However, once I add a loader to the parent route, the behavior shifts and starts to resemble what I was seeing in framework mode (errors bubbling to root rather than being scoped on initial load). Even if the parent loader is in noway dependant on the middleware.

[brophdawg11]

Do you see framework mode ever supporting this type of decisions, (perhaps with some bundler-level magic) to allow more control over when and which parts of route modules are resolved up-front vs lazily?

I don't. Feel free to open a proposal outlining what you are looking for.

once I add a loader to the parent route

Yes, this is expected for the exact same reason outlined above. React Router has a hard rule that if a route has a loader, it does not render that route's Component unless it has loader data available. That avoids needing to do a bunch of null checks in your component (happy path). You are doing 3 specific things to cause this (expected) behavior:

• You have a loader on the root route
• You are directly loading this /edit route
• You are throwing from middleware before the root loader has executed

Therefore, the deepest we can possibly render is the root error boundary. We cannot render the root component because it has no loader data, and therefore we cannot possibly render a child error boundary inside the Outlet of the root component.

[VillePakarinenPosti]

Thank you for your patience on the matter 🙏

My intuition in the previous case was that since the throwing middleware belonged to a child route, it wouldn’t block the eager parent layout module (layout, error boundary + loader) from executing, because from the route hierarchy’s perspective there was no direct dependency to the middleware.

It seems the only viable option for me is to move toward a solution that doesn’t rely on middleware throwing, since the UX requirements in my more complex SPA depend on preserving certain layout composition, and bubbling all the way to the root after a document reload won’t work.

Anyway, I really appreciate you taking the time to explain the whole story so clearly and also for the amazing work you’ve done with React Router. Cheers 🙌