Skip to content

docs(js): Update react router server instrumentation #18391

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
chargome merged 3 commits into from
Jun 15, 2026
Merged

docs(js): Update react router server instrumentation #18391

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d0b17a8
update docs
chargome Jun 12, 2026
b358211
dead link
chargome Jun 12, 2026
f646941
Merge branch 'master' into cg/rr-server-updates
chargome Jun 15, 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
1 change: 0 additions & 1 deletion docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -467,7 +467,6 @@ Our next recommended steps for you are:
- Explore [practical guides](/guides) on what to monitor, log, track, and investigate after setup
- Learn how to <PlatformLink to="/usage">manually capture errors</PlatformLink>
- Continue to <PlatformLink to="/configuration">customize your configuration</PlatformLink>
- Make use of [React Router-specific features](/platforms/javascript/guides/react-router/features/)
- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts

<Expandable permalink={false} title="Are you having problems setting up the SDK?">
Expand Down
16 changes: 0 additions & 16 deletions docs/platforms/javascript/guides/react-router/features/index.mdx
View file
Open in desktop

This file was deleted.

218 changes: 0 additions & 218 deletions docs/platforms/javascript/guides/react-router/features/instrumentation-api.mdx
View file
Open in desktop

This file was deleted.

55 changes: 14 additions & 41 deletions docs/platforms/javascript/guides/react-router/manual-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ description: "Learn how to manually set up Sentry in your React Router v7 app an

<Alert level="info">
Looking for automatic setup with `sentry init` or the React Router Framework
Mode wizard? Follow the [React Router quickstart](/platforms/javascript/guides/react-router/)
instead.
Continue with this guide to set up Sentry manually.
Mode wizard? Follow the [React Router
quickstart](/platforms/javascript/guides/react-router/) instead. Continue with
this guide to set up Sentry manually.
</Alert>

<PlatformContent includePath="getting-started-prerequisites" />
Expand Down Expand Up @@ -198,49 +198,16 @@ startTransition(() => {

### Configure Server-Side Sentry

<Expandable level="warning" title="Limited Node support for auto-instrumentation" permalink>
<Expandable level="warning" title="Limited Node support for OpenTelemetry auto-instrumentation" permalink>

Automatic server-side instrumentation is currently only supported on:
Sentry's OpenTelemetry-based auto-instrumentation (loaded through `instrument.server.mjs`) is currently only supported on:

- **Node 20:** Version \<20.19
- **Node 22:** Version \<22.12

If you're on a different version, you have two options:
This restriction **doesn't** affect tracing for loaders, actions, middleware, and request handlers. Those are instrumented through React Router's [instrumentation API](https://reactrouter.com/how-to/instrumentation) (the `instrumentations` export shown below, React Router 7.15+), which works on all Node versions.

1. **Recommended**: Use the stable <PlatformLink to="/features/instrumentation-api/">Instrumentation API</PlatformLink> (React Router 7.15+) for automatic tracing without Node version restrictions. React Router 7.9.5 introduced an earlier unstable API with `unstable_*` names.
2. **Alternative**: Use our manual server wrappers (shown below)

For server loaders use `wrapServerLoader`:

```ts
import * as Sentry from "@sentry/react-router";

export const loader = Sentry.wrapServerLoader(
{
name: "Load Some Data",
description: "Loads some data from the db",
},
async ({ params }) => {
// ... your loader logic
}
);
```

For server actions use `wrapServerAction`:

```ts
import * as Sentry from "@sentry/react-router";

export const action = Sentry.wrapServerAction(
{
name: "Submit Form Data",
description: "Processes form submission data",
},
async ({ request }) => {
// ... your action logic
}
);
```
On unsupported Node versions, you'll only lose auto-instrumentation for lower-level operations such as outgoing HTTP requests and database queries.

</Expandable>

Expand Down Expand Up @@ -298,7 +265,9 @@ Sentry.init({
<SplitSection>
<SplitSectionText>

Next, replace the default `handleRequest` and `handleError` functions in your `entry.server.tsx` file with Sentry's wrapped versions:
Next, replace the default `handleRequest` and `handleError` functions in your `entry.server.tsx` file with Sentry's wrapped versions, and export `instrumentations` to enable automatic tracing.

Exporting `instrumentations` uses React Router's [instrumentation API](https://reactrouter.com/how-to/instrumentation) (React Router 7.15+) to automatically create spans for all loaders, actions, middleware, and request handlers — no need to wrap them individually.

</SplitSectionText>
<SplitSectionCode>
Expand All @@ -322,6 +291,10 @@ Next, replace the default `handleRequest` and `handleError` functions in your `e
+ logErrors: false
+});

+// Automatically instruments all server loaders, actions, middleware,
+// and request handlers. Requires React Router 7.15+.
+export const instrumentations = [Sentry.createSentryServerInstrumentation()];

// ... rest of your server entry
```

Expand Down
7 changes: 6 additions & 1 deletion redirects.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -963,6 +963,10 @@ const userDocsRedirects = [
source: '/platforms/javascript/guides/aws-lambda/cjs-npm__v9.x/',
destination: '/platforms/javascript/guides/aws-lambda/install/cjs-npm__v9.x/',
},
{
source: '/platforms/javascript/guides/react-router/features/instrumentation-api/',
destination: '/platforms/javascript/guides/react-router/manual-setup/',
},
Comment thread
sentry[bot] marked this conversation as resolved.
Comment on lines +966 to +969

@sentry sentry Bot Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Bug: A missing redirect for the removed /features/ documentation index page will cause 404 errors for users accessing the old URL.
Severity: LOW

Suggested Fix

Add a new redirect entry in redirects.js to forward users from the old features index path to the new manual setup guide. The entry should look like: { source: '/platforms/javascript/guides/react-router/features/', destination: '/platforms/javascript/guides/react-router/manual-setup/' }.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: redirects.js#L966-L969

Potential issue: The pull request removes the documentation page at
`docs/platforms/javascript/guides/react-router/features/index.mdx` but does not add a
corresponding redirect in `redirects.js`. While a redirect was correctly added for the
`instrumentation-api` sub-page, the parent features index page URL is now unhandled.
Consequently, any user attempting to access
`/platforms/javascript/guides/react-router/features/` from an old bookmark, a search
engine result, or an external link will receive a 404 error instead of being redirected
to the new content location.

{
source: '/platforms/javascript/guides/nextjs/sourcemaps/uploading/',
destination: '/platforms/javascript/guides/nextjs/sourcemaps/',
Expand Down Expand Up @@ -1868,7 +1872,8 @@ const userDocsRedirects = [
},
{
source: '/product/insights/mobile-vitals/screen-loads/',
destination: '/product/dashboards/sentry-dashboards/mobile/mobile-vitals/screen-loads/',
destination:
'/product/dashboards/sentry-dashboards/mobile/mobile-vitals/screen-loads/',
},
{
source: '/product/insights/mobile-vitals/:path*',
Expand Down
Loading