From 90988c24d279e8fb9f08c450df25b656ab61b03c Mon Sep 17 00:00:00 2001
From: Charly Gomez <charly.gomez1310@gmail.com>
Date: Wed, 22 Jul 2026 17:42:35 +0200
Subject: [PATCH] feat(react-router): Make instrumentation API the default

Wire the React Router instrumentation API in the documented client and server
setup so users no longer fall through to the OTel path. Deprecate the
`clientInstrumentation` getter in favor of the standalone
`createSentryClientInstrumentation()` export, mirroring the server-side API.

Fixes #22412

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/react-router/README.md                | 18 ++++++++++++------
 .../src/client/tracingIntegration.ts           |  4 ++++
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/packages/react-router/README.md b/packages/react-router/README.md
index 6711c2311335..139ff863f6d1 100644
--- a/packages/react-router/README.md
+++ b/packages/react-router/README.md
@@ -45,7 +45,7 @@ import { HydratedRouter } from 'react-router/dom';
 
 Sentry.init({
   dsn: '___PUBLIC_DSN___',
-  integrations: [Sentry.browserTracingIntegration()],
+  integrations: [Sentry.reactRouterTracingIntegration()],
 
   tracesSampleRate: 1.0, //  Capture 100% of the transactions
 
@@ -57,7 +57,7 @@ startTransition(() => {
   hydrateRoot(
     document,
     <StrictMode>
-      <HydratedRouter />
+      <HydratedRouter instrumentations={[Sentry.createSentryClientInstrumentation()]} onError={Sentry.sentryOnError} />
     </StrictMode>,
   );
 });
@@ -113,9 +113,11 @@ Sentry.init({
 });
 ```
 
-In your `entry.server.tsx` file, export the `handleError` function:
+In your `entry.server.tsx` file, import the instrumentation file at the very top, export the
+`instrumentations` array, and export the `handleError` function:
 
 ```tsx
+import './instrument.server.mjs';
 import * as Sentry from '@sentry/react-router';
 import { type HandleErrorFunction } from 'react-router';
 
@@ -128,13 +130,17 @@ export const handleError: HandleErrorFunction = (error, { request }) => {
     console.error(error);
   }
 };
+
+// Register the Sentry server instrumentation so loaders, actions and middleware are traced.
+export const instrumentations = [Sentry.createSentryServerInstrumentation()];
 // ... rest of your server entry
 ```
 
-### Update Scripts
+### Loading the Instrumentation via `--import` (Alternative)
 
-Since React Router is running in ESM mode, you need to use the `--import` command line options to load our server-side instrumentation module before the application starts.
-Update the `start` and `dev` script to include the instrumentation file:
+Instead of importing the instrumentation file at the top of `entry.server.tsx`, you can load it before
+the application starts via the `--import` command line option. Since React Router runs in ESM mode,
+update the `start` and `dev` scripts accordingly:
 
 ```json
 "scripts": {
diff --git a/packages/react-router/src/client/tracingIntegration.ts b/packages/react-router/src/client/tracingIntegration.ts
index 45f84f1725ae..866c40b99586 100644
--- a/packages/react-router/src/client/tracingIntegration.ts
+++ b/packages/react-router/src/client/tracingIntegration.ts
@@ -26,6 +26,10 @@ export interface ReactRouterTracingIntegrationOptions {
 export interface ReactRouterTracingIntegration extends Integration {
   /**
    * Client instrumentation to pass to `HydratedRouter`'s `instrumentations` prop.
+   *
+   * @deprecated Use the standalone `createSentryClientInstrumentation()` export instead and pass its
+   * result to `HydratedRouter`'s `instrumentations` prop. This mirrors the server-side
+   * `createSentryServerInstrumentation()` API. Will be removed in a future major.
    */
   readonly clientInstrumentation: ClientInstrumentation;
 }