feat(react-router): Switch to new stable instrumentations api (#1265)

* add new api

* fix tests

Author: chargome

e2e-tests/test-applications/react-router-test-app/package.json

@@ -10,13 +10,13 @@
     "typecheck": "react-router typegen && tsc"
   },
   "dependencies": {
-    "@react-router/dev": "^7.12.0",
-    "@react-router/node": "^7.12.0",
-    "@react-router/serve": "^7.12.0",
+    "@react-router/dev": "^7.15.0",
+    "@react-router/node": "^7.15.0",
+    "@react-router/serve": "^7.15.0",
     "isbot": "^4.4.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "react-router": "^7.12.0"
+    "react-router": "^7.15.0"
   },
   "devDependencies": {
     "@types/react": "^18.3.9",

e2e-tests/tests/react-router-instrumentation-api.test.ts

@@ -15,7 +15,7 @@ import {
 //@ts-expect-error - clifty is ESM only
 import { KEYS, withEnv } from 'clifty';
 
-// Expects React Router >= 7.9.5
+// Expects React Router >= 7.15.0
 async function runWizardWithInstrumentationAPI(
   projectDir: string,
 ): Promise<number> {
@@ -90,7 +90,7 @@ describe('React Router Instrumentation API', () => {
         '@sentry/react-router',
         'const tracing = Sentry.reactRouterTracingIntegration({ useInstrumentationAPI: true });',
         'integrations: [tracing',
-        'unstable_instrumentations={[tracing.clientInstrumentation]}',
+        'instrumentations={[tracing.clientInstrumentation]}',
       ]);
     });
 
@@ -100,7 +100,7 @@ describe('React Router Instrumentation API', () => {
         '@sentry/react-router',
         'Sentry.wrapSentryHandleRequest(',
         'export const handleError = Sentry.createSentryHandleError(',
-        'export const unstable_instrumentations = [Sentry.createSentryServerInstrumentation()]',
+        'export const instrumentations = [Sentry.createSentryServerInstrumentation()]',
       ]);
     });
 

src/react-router/codemods/client.entry.ts

@@ -112,7 +112,7 @@ Sentry.init({
       props.push('onError={Sentry.sentryOnError}');
     }
     if (addInstrProp) {
-      props.push('unstable_instrumentations={[tracing.clientInstrumentation]}');
+      props.push('instrumentations={[tracing.clientInstrumentation]}');
     }
     clack.log.warn(
       `Could not find ${chalk.cyan(
@@ -201,7 +201,7 @@ function addOnErrorToHydratedRouter(ast: t.Program): boolean {
 function addInstrumentationPropsToHydratedRouter(ast: t.Program): boolean {
   return addPropToHydratedRouter(
     ast,
-    'unstable_instrumentations',
+    'instrumentations',
     recast.types.builders.arrayExpression([
       recast.types.builders.memberExpression(
         recast.types.builders.identifier('tracing'),

src/react-router/codemods/server-entry.ts

@@ -43,54 +43,51 @@ export async function instrumentServerEntry(
   instrumentHandleRequest(serverEntryAst);
 
   if (useInstrumentationAPI) {
-    instrumentUnstableInstrumentations(serverEntryAst);
+    instrumentInstrumentations(serverEntryAst);
   }
 
   await writeFile(serverEntryAst.$ast, serverEntryPath);
 }
 
-function instrumentUnstableInstrumentations(
+function instrumentInstrumentations(
   originalEntryServerMod: ProxifiedModule<any>,
 ): void {
   const originalEntryServerModAST = originalEntryServerMod.$ast as t.Program;
 
-  const hasUnstableInstrumentations = originalEntryServerModAST.body.some(
-    (node) => {
-      if (
-        node.type !== 'ExportNamedDeclaration' ||
-        node.declaration?.type !== 'VariableDeclaration'
-      ) {
-        return false;
-      }
-
-      const declarations = node.declaration.declarations;
-      if (!declarations || declarations.length === 0) {
-        return false;
-      }
+  const hasInstrumentations = originalEntryServerModAST.body.some((node) => {
+    if (
+      node.type !== 'ExportNamedDeclaration' ||
+      node.declaration?.type !== 'VariableDeclaration'
+    ) {
+      return false;
+    }
 
-      const firstDeclaration = declarations[0];
-      if (!firstDeclaration || firstDeclaration.type !== 'VariableDeclarator') {
-        return false;
-      }
+    const declarations = node.declaration.declarations;
+    if (!declarations || declarations.length === 0) {
+      return false;
+    }
 
-      const id = firstDeclaration.id;
-      return (
-        id &&
-        id.type === 'Identifier' &&
-        id.name === 'unstable_instrumentations'
-      );
-    },
-  );
+    const firstDeclaration = declarations[0];
+    if (!firstDeclaration || firstDeclaration.type !== 'VariableDeclarator') {
+      return false;
+    }
 
-  if (hasUnstableInstrumentations) {
-    debug(
-      'unstable_instrumentations export already exists, skipping adding it again',
+    const id = firstDeclaration.id;
+    return (
+      id &&
+      id.type === 'Identifier' &&
+      (id.name === 'instrumentations' ||
+        id.name === 'unstable_instrumentations')
     );
+  });
+
+  if (hasInstrumentations) {
+    debug('instrumentations export already exists, skipping adding it again');
     return;
   }
 
   const instrumentationsExport = recast.parse(
-    `export const unstable_instrumentations = [Sentry.createSentryServerInstrumentation()];`,
+    `export const instrumentations = [Sentry.createSentryServerInstrumentation()];`,
   ).program.body[0];
 
   originalEntryServerModAST.body.push(instrumentationsExport);

src/react-router/react-router-wizard.ts

@@ -190,7 +190,7 @@ Please create your entry files manually using React Router v7 commands.`);
     const detectedVersion = getReactRouterVersion(packageJson) ?? 'unknown';
     clack.log.warn(
       `The Instrumentation API requires React Router ${chalk.cyan(
-        '>=7.9.5',
+        '>=7.15.0',
       )} (detected ${chalk.cyan(
         detectedVersion,
       )}). Your version does not meet this requirement.\n` +

src/react-router/sdk-setup.ts

@@ -202,7 +202,7 @@ export function supportsInstrumentationAPI(
     return false;
   }
 
-  return gte(minVer, '7.9.5');
+  return gte(minVer, '7.15.0');
 }
 
 export async function initializeSentryOnEntryClient(

src/react-router/templates.ts

@@ -139,7 +139,7 @@ startTransition(() => {
       ${plus(
         `<HydratedRouter${
           useOnError ? ' onError={Sentry.sentryOnError}' : ''
-        } unstable_instrumentations={[tracing.clientInstrumentation]} />`,
+        } instrumentations={[tracing.clientInstrumentation]} />`,
       )}
     </StrictMode>
   );
@@ -230,7 +230,7 @@ ${plus(`export const handleError = Sentry.createSentryHandleError({
 });`)}
 
 ${plus(`// Enable automatic server-side instrumentation for loaders, actions, middleware
-export const unstable_instrumentations = [Sentry.createSentryServerInstrumentation()];`)}
+export const instrumentations = [Sentry.createSentryServerInstrumentation()];`)}
 
 // ... rest of your server entry`),
     );

test/react-router/codemods/client-entry.test.ts

@@ -294,7 +294,7 @@ describe('instrumentClientEntry', () => {
       );
       expect(modifiedContent).toContain('integrations: [tracing]');
       expect(modifiedContent).toContain(
-        'unstable_instrumentations={[tracing.clientInstrumentation]}',
+        'instrumentations={[tracing.clientInstrumentation]}',
       );
     });
 
@@ -317,7 +317,7 @@ describe('instrumentClientEntry', () => {
         'integrations: [tracing, Sentry.replayIntegration()]',
       );
       expect(modifiedContent).toContain(
-        'unstable_instrumentations={[tracing.clientInstrumentation]}',
+        'instrumentations={[tracing.clientInstrumentation]}',
       );
     });
 
@@ -346,7 +346,7 @@ describe('instrumentClientEntry', () => {
       expect(modifiedContent).toContain(
         'Sentry.reactRouterTracingIntegration()',
       );
-      expect(modifiedContent).not.toContain('unstable_instrumentations');
+      expect(modifiedContent).not.toContain('instrumentations');
     });
   });
 });

test/react-router/codemods/server-entry.test.ts

@@ -610,7 +610,7 @@ describe('Instrumentation API', () => {
     }
   });
 
-  it('should add unstable_instrumentations export when useInstrumentationAPI is true', async () => {
+  it('should add instrumentations export when useInstrumentationAPI is true', async () => {
     const basicContent = fs.readFileSync(
       path.join(fixturesDir, 'basic.tsx'),
       'utf8',
@@ -626,11 +626,11 @@ describe('Instrumentation API', () => {
       'import * as Sentry from "@sentry/react-router";',
     );
     expect(modifiedContent).toContain(
-      'export const unstable_instrumentations = [Sentry.createSentryServerInstrumentation()];',
+      'export const instrumentations = [Sentry.createSentryServerInstrumentation()];',
     );
   });
 
-  it('should not add unstable_instrumentations export when useInstrumentationAPI is false', async () => {
+  it('should not add instrumentations export when useInstrumentationAPI is false', async () => {
     const basicContent = fs.readFileSync(
       path.join(fixturesDir, 'basic.tsx'),
       'utf8',
@@ -642,18 +642,18 @@ describe('Instrumentation API', () => {
 
     const modifiedContent = fs.readFileSync(tmpFile, 'utf8');
 
-    expect(modifiedContent).not.toContain('unstable_instrumentations');
+    expect(modifiedContent).not.toContain('instrumentations');
     expect(modifiedContent).not.toContain('createSentryServerInstrumentation');
   });
 
-  it('should not duplicate unstable_instrumentations export if already present', async () => {
+  it('should not duplicate instrumentations export if already present', async () => {
     const contentWithInstrumentations = `
 import { ServerRouter } from 'react-router';
 import * as Sentry from '@sentry/react-router';
 
 export default function handleRequest() {}
 export const handleError = () => {};
-export const unstable_instrumentations = [Sentry.createSentryServerInstrumentation()];
+export const instrumentations = [Sentry.createSentryServerInstrumentation()];
 `;
 
     fs.writeFileSync(tmpFile, contentWithInstrumentations);
@@ -662,8 +662,26 @@ export const unstable_instrumentations = [Sentry.createSentryServerInstrumentati
 
     const modifiedContent = fs.readFileSync(tmpFile, 'utf8');
 
-    const count = (modifiedContent.match(/unstable_instrumentations/g) || [])
-      .length;
+    const count = (modifiedContent.match(/\binstrumentations\b/g) || []).length;
     expect(count).toBe(1);
   });
+
+  it('should not duplicate if legacy unstable_instrumentations export is already present', async () => {
+    const contentWithLegacy = `
+import { ServerRouter } from 'react-router';
+import * as Sentry from '@sentry/react-router';
+
+export default function handleRequest() {}
+export const handleError = () => {};
+export const unstable_instrumentations = [Sentry.createSentryServerInstrumentation()];
+`;
+
+    fs.writeFileSync(tmpFile, contentWithLegacy);
+
+    await instrumentServerEntry(tmpFile, true);
+
+    const modifiedContent = fs.readFileSync(tmpFile, 'utf8');
+
+    expect(modifiedContent).not.toContain('export const instrumentations =');
+  });
 });

test/react-router/sdk-setup.test.ts

@@ -181,20 +181,20 @@ describe('React Router SDK Setup', () => {
   });
 
   describe('supportsInstrumentationAPI', () => {
-    it('should return true for React Router v7.9.5 or higher', () => {
+    it('should return true for React Router v7.15.0 or higher', () => {
       expect(
         supportsInstrumentationAPI({
-          dependencies: { '@react-router/dev': '7.9.5' },
+          dependencies: { '@react-router/dev': '7.15.0' },
         }),
       ).toBe(true);
       expect(
         supportsInstrumentationAPI({
-          dependencies: { '@react-router/dev': '^7.9.5' },
+          dependencies: { '@react-router/dev': '^7.15.0' },
         }),
       ).toBe(true);
       expect(
         supportsInstrumentationAPI({
-          dependencies: { '@react-router/dev': '7.10.0' },
+          dependencies: { '@react-router/dev': '7.16.0' },
         }),
       ).toBe(true);
       expect(
@@ -204,15 +204,15 @@ describe('React Router SDK Setup', () => {
       ).toBe(true);
       expect(
         supportsInstrumentationAPI({
-          devDependencies: { '@react-router/dev': '7.9.5' },
+          devDependencies: { '@react-router/dev': '7.15.0' },
         }),
       ).toBe(true);
     });
 
-    it('should return false for React Router versions below v7.9.5', () => {
+    it('should return false for React Router versions below v7.15.0', () => {
       expect(
         supportsInstrumentationAPI({
-          dependencies: { '@react-router/dev': '7.9.4' },
+          dependencies: { '@react-router/dev': '7.14.0' },
         }),
       ).toBe(false);
       expect(
@@ -222,7 +222,7 @@ describe('React Router SDK Setup', () => {
       ).toBe(false);
       expect(
         supportsInstrumentationAPI({
-          dependencies: { '@react-router/dev': '7.9.0' },
+          dependencies: { '@react-router/dev': '7.9.5' },
         }),
       ).toBe(false);
     });
@@ -239,12 +239,12 @@ describe('React Router SDK Setup', () => {
     it('should handle semver range specifiers correctly', () => {
       expect(
         supportsInstrumentationAPI({
-          dependencies: { '@react-router/dev': '~7.9.5' },
+          dependencies: { '@react-router/dev': '~7.15.0' },
         }),
       ).toBe(true);
       expect(
         supportsInstrumentationAPI({
-          dependencies: { '@react-router/dev': '>=7.9.5' },
+          dependencies: { '@react-router/dev': '>=7.15.0' },
         }),
       ).toBe(true);
     });