Skip to content

Document lazyRouteManifest option for React Router v6 and v7 #16397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
s1gr1d merged 5 commits into from
Feb 23, 2026
Merged

Document lazyRouteManifest option for React Router v6 and v7 #16397

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
fc58840
Document lazyRouteManifest option for React Router v6 and v7
onurtemizkan Feb 16, 2026
3d9bb0e
Merge branch 'master' into onur/react-router-lazy-routes-manifest
onurtemizkan Feb 16, 2026
657d0ad
Address review feedback
onurtemizkan Feb 17, 2026
99343d0
Move paragraph above code snippet
onurtemizkan Feb 19, 2026
3ec2939
Merge branch 'master' into onur/react-router-lazy-routes-manifest
s1gr1d Feb 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions docs/platforms/javascript/guides/react/features/react-router/v6.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,55 @@ ReactDOM.render(

Now, Sentry should generate `pageload`/`navigation` transactions with parameterized transaction names (for example, `/teams/:teamid/user/:userid`), where applicable. This is only needed at the top level of your app, unlike React Router v4/v5, which required wrapping every `<Route />` you wanted parametrized.

## Static Route Manifest

_Available in `@sentry/react` version `10.39.0` and above._
Copy link
Copy Markdown
Member

@chargome chargome Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a component for this!


When using [`patchRoutesOnNavigation`](https://reactrouter.com/6.30.3/routers/create-browser-router#optspatchroutesonnavigation) to dynamically load route definitions, the full route hierarchy isn't available to Sentry until each route is navigated to. This can cause transactions to receive incomplete or wildcard names (for example, `/users/*` instead of `/users/:userId`).

To ensure accurate transaction names, you can provide a static list of route patterns via the `lazyRouteManifest` option. When provided, Sentry uses this manifest as the primary source for determining transaction names without needing to wait for route modules to load.

<Alert level="warning" title="Important">
`lazyRouteManifest` requires `enableAsyncRouteHandlers: true` to be set on the integration.
Copy link
Copy Markdown
Collaborator

@inventarSarah inventarSarah Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this alert is needed because we clearly state the dependency below + it's in the code example


</Alert>

Copy link
Copy Markdown
Collaborator

@inventarSarah inventarSarah Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's add the explanation here:

Suggested change
To use `lazyRouteManifest`, you need to set `enableAsyncRouteHandlers: true` in your `reactRouterV6BrowserTracingIntegration` configuration:

```javascript {20-27}
import React from "react";
import {
createRoutesFromChildren,
matchRoutes,
useLocation,
useNavigationType,
} from "react-router-dom";

import * as Sentry from "@sentry/react";

Sentry.init({
dsn: "___PUBLIC_DSN___",
integrations: [
Sentry.reactRouterV6BrowserTracingIntegration({
useEffect: React.useEffect,
useLocation,
useNavigationType,
createRoutesFromChildren,
matchRoutes,
enableAsyncRouteHandlers: true,
lazyRouteManifest: [
"/users",
"/users/:userId",
"/users/:userId/settings",
"/dashboard",
"/dashboard/analytics",
],
}),
],
tracesSampleRate: 1.0,
});
```

Add the `enableAsyncRouteHandlers` and `lazyRouteManifest` options to your `reactRouterV6BrowserTracingIntegration` configuration. Keep the `lazyRouteManifest` array in sync with your route definitions. Any route that doesn't match a pattern in the manifest will fall back to the default behavior, which may result in incomplete transaction names until the route is visited.
Copy link
Copy Markdown
Collaborator

@inventarSarah inventarSarah Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Add the `enableAsyncRouteHandlers` and `lazyRouteManifest` options to your `reactRouterV6BrowserTracingIntegration` configuration. Keep the `lazyRouteManifest` array in sync with your route definitions. Any route that doesn't match a pattern in the manifest will fall back to the default behavior, which may result in incomplete transaction names until the route is visited.
Make sure to keep the `lazyRouteManifest` array in sync with your route definitions: if you add, remove, or change routes in your app, update this list accordingly. Any route that doesn't match a pattern in the manifest will fall back to the default behavior, which may result in incomplete transaction names until the route is visited.

Let's move the first sentence above the code snippet.
I also wanted to clarify what we mean by "in sync" but maybe that's not necessary -- just a suggestion :)

Copy link
Copy Markdown
Collaborator

@inventarSarah inventarSarah Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

q: in the SDK PR you wrote:

This manifest is primarily for lazy routes, but the users can also add their non-lazy routes here for convenience or consistency.

Do you think this is clear to our users, or should we also add this to the docs (maybe in a note alert)?


## Set Up a Custom Error Boundary

When using `react-router`, errors thrown inside route elements will only be re-thrown in **development mode** while using [`strict mode`](https://react.dev/reference/react/StrictMode).\
Expand Down
53 changes: 51 additions & 2 deletions docs/platforms/javascript/guides/react/features/react-router/v7.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ sidebar_order: 10
---

<Alert level="info" title="Looking for framework mode?">
React Router v7 (framework mode) is currently in Beta, check out
the docs [here](/platforms/javascript/guides/react-router/).
React Router v7 (framework mode) is currently in Beta, check out the docs
[here](/platforms/javascript/guides/react-router/).
</Alert>
Apply the following setup steps based on your routing method and create a
[custom error boundary](#set-up-a-custom-error-boundary) to make sure Sentry
Expand Down Expand Up @@ -155,6 +155,55 @@ ReactDOM.render(

Now, Sentry should generate `pageload`/`navigation` transactions with parameterized transaction names (for example, `/teams/:teamid/user/:userid`), where applicable. This is only needed at the top level of your app, unlike React Router v4/v5, which required wrapping every `<Route />` you wanted parametrized.

## Static Route Manifest
Copy link
Copy Markdown
Collaborator

@inventarSarah inventarSarah Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could it make sense to create an include for this?

Copy link
Copy Markdown
Collaborator Author

@onurtemizkan onurtemizkan Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This would need to exclude the code snippet, I think it can stay like this for now.


_Available in `@sentry/react` version `10.39.0` and above._

When using [`patchRoutesOnNavigation`](https://reactrouter.com/api/data-routers/createBrowserRouter#optspatchroutesonnavigation) to dynamically load route definitions, the full route hierarchy isn't available to Sentry until each route is navigated to. This can cause transactions to receive incomplete or wildcard names (for example, `/users/*` instead of `/users/:userId`).

To ensure accurate transaction names, you can provide a static list of route patterns via the `lazyRouteManifest` option. When provided, Sentry uses this manifest as the primary source for determining transaction names without needing to wait for route modules to load.

<Alert level="warning" title="Important">
`lazyRouteManifest` requires `enableAsyncRouteHandlers: true` to be set on the integration.

</Alert>

```javascript {20-27}
import React from "react";
import {
createRoutesFromChildren,
matchRoutes,
useLocation,
useNavigationType,
} from "react-router";

import * as Sentry from "@sentry/react";

Sentry.init({
dsn: "___PUBLIC_DSN___",
integrations: [
Sentry.reactRouterV7BrowserTracingIntegration({
useEffect: React.useEffect,
useLocation,
useNavigationType,
createRoutesFromChildren,
matchRoutes,
enableAsyncRouteHandlers: true,
lazyRouteManifest: [
"/users",
"/users/:userId",
"/users/:userId/settings",
"/dashboard",
"/dashboard/analytics",
],
}),
],
tracesSampleRate: 1.0,
});
```

Add the `enableAsyncRouteHandlers` and `lazyRouteManifest` options to your `reactRouterV7BrowserTracingIntegration` configuration. Keep the `lazyRouteManifest` array in sync with your route definitions. Any route that doesn't match a pattern in the manifest will fall back to the default behavior, which may result in incomplete transaction names until the route is visited.

## Set Up a Custom Error Boundary

When using `react-router`, errors thrown inside route elements will only be re-thrown in **development mode** while using [`strict mode`](https://react.dev/reference/react/StrictMode).\
Expand Down