feat(react-router): Add basic package (#15289)

Author: chargome

Diff for: dev-packages/e2e-tests/verdaccio-config/config.yaml

@@ -122,6 +122,12 @@ packages:
     unpublish: $all
     # proxy: npmjs # Don't proxy for E2E tests!
 
+  '@sentry/react-router':
+    access: $all
+    publish: $all
+    unpublish: $all
+    # proxy: npmjs # Don't proxy for E2E tests!
+
   '@sentry/remix':
     access: $all
     publish: $all

Diff for: package.json

@@ -73,6 +73,7 @@
     "packages/opentelemetry",
     "packages/profiling-node",
     "packages/react",
+    "packages/react-router",
     "packages/remix",
     "packages/replay-internal",
     "packages/replay-canvas",

Diff for: packages/react-router/.eslintrc.js

@@ -0,0 +1,15 @@
+module.exports = {
+  env: {
+    browser: true,
+    node: true,
+  },
+  overrides: [
+    {
+      files: ['vite.config.ts'],
+      parserOptions: {
+        project: ['tsconfig.test.json'],
+      },
+    },
+  ],
+  extends: ['../../.eslintrc.js'],
+};

Diff for: packages/react-router/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2025 Functional Software, Inc. dba Sentry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Diff for: packages/react-router/README.md

@@ -0,0 +1,146 @@
+<p align="center">
+  <a href="https://sentry.io/?utm_source=github&utm_medium=logo" target="_blank">
+    <img src="https://sentry-brand.storage.googleapis.com/sentry-wordmark-dark-280x84.png" alt="Sentry" width="280" height="84">
+  </a>
+</p>
+
+# Official Sentry SDK for React Router (Framework) (EXPERIMENTAL)
+
+[![npm version](https://img.shields.io/npm/v/@sentry/react-router.svg)](https://www.npmjs.com/package/@sentry/react-router)
+[![npm dm](https://img.shields.io/npm/dm/@sentry/react-router.svg)](https://www.npmjs.com/package/@sentry/react-router)
+[![npm dt](https://img.shields.io/npm/dt/@sentry/react-router.svg)](https://www.npmjs.com/package/@sentry/react-router)
+
+> [!WARNING]
+> This SDK is considered ⚠️ **experimental and in an alpha state**. It may experience breaking changes. Please reach out
+> on [GitHub](https://github.com/getsentry/sentry-javascript/issues/) if you have any feedback or concerns. This
+> SDK is for [React Router (framework)](https://reactrouter.com/start/framework/installation). If you're using [React Router (library)](https://reactrouter.com/start/library/installation) see our
+> [React SDK here](https://docs.sentry.io/platforms/javascript/guides/react/features/react-router/v7/).
+
+## Links
+
+- [Official SDK Docs](https://docs.sentry.io/platforms/javascript/guides/react-router/)
+
+## General
+
+This package is a wrapper around `@sentry/node` for the server and `@sentry/browser` for the client side.
+
+## Manual Setup
+
+### Expose Hooks
+
+React Router exposes two hooks in your `app` folder (`entry.client.tsx` and `entry.server.tsx`).
+If you do not see these two files, expose them with the following command:
+
+```bash
+npx react-router reveal
+```
+
+### Client-Side Setup
+
+Initialize the SDK in your `entry.client.tsx` file:
+
+```tsx
+import * as Sentry from '@sentry/react-router';
+import { startTransition, StrictMode } from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { HydratedRouter } from 'react-router/dom';
+
+Sentry.init({
+  dsn: '___PUBLIC_DSN___',
+  integrations: [Sentry.browserTracingIntegration()],
+
+  tracesSampleRate: 1.0, //  Capture 100% of the transactions
+
+  // Set `tracePropagationTargets` to declare which URL(s) should have trace propagation enabled
+  tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/],
+});
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <HydratedRouter />
+    </StrictMode>,
+  );
+});
+```
+
+Now, update your `app/root.tsx` file to report any unhandled errors from your global error boundary:
+
+```tsx
+import * as Sentry from '@sentry/react-router';
+
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+  let message = 'Oops!';
+  let details = 'An unexpected error occurred.';
+  let stack: string | undefined;
+
+  if (isRouteErrorResponse(error)) {
+    message = error.status === 404 ? '404' : 'Error';
+    details = error.status === 404 ? 'The requested page could not be found.' : error.statusText || details;
+  } else if (error && error instanceof Error) {
+    // you only want to capture non 404-errors that reach the boundary
+    Sentry.captureException(error);
+    if (import.meta.env.DEV) {
+      details = error.message;
+      stack = error.stack;
+    }
+  }
+
+  return (
+    <main>
+      <h1>{message}</h1>
+      <p>{details}</p>
+      {stack && (
+        <pre>
+          <code>{stack}</code>
+        </pre>
+      )}
+    </main>
+  );
+}
+// ...
+```
+
+### Server-Side Setup
+
+Create an `instrument.server.mjs` file in the root of your app:
+
+```js
+import * as Sentry from '@sentry/node';
+
+Sentry.init({
+  dsn: '___PUBLIC_DSN___',
+  tracesSampleRate: 1.0, // Capture 100% of the transactions
+});
+```
+
+In your `entry.server.tsx` file, export the `handleError` function:
+
+```tsx
+import * as Sentry from '@sentry/node';
+import { type HandleErrorFunction } from 'react-router';
+
+export const handleError: HandleErrorFunction = (error, { request }) => {
+  // React Router may abort some interrupted requests, report those
+  if (!request.signal.aborted) {
+    Sentry.captureException(error);
+
+    // make sure to still log the error so you can see it
+    console.error(error);
+  }
+};
+// ... rest of your server entry
+```
+
+### Update Scripts
+
+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:
+
+```json
+"scripts": {
+  "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router dev",
+  "start": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router-serve ./build/server/index.js",
+}
+```

Diff for: packages/react-router/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@sentry/react-router",
+  "version": "9.0.0-alpha.2",
+  "description": "Official Sentry SDK for React Router (Framework)",
+  "repository": "git://github.com/getsentry/sentry-javascript.git",
+  "homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/react-router",
+  "author": "Sentry",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "/build"
+  ],
+  "main": "build/cjs/index.server.js",
+  "module": "build/esm/index.server.js",
+  "browser": "build/esm/index.client.js",
+  "types": "build/types/index.types.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./build/types/index.types.d.ts",
+      "browser": {
+        "import": "./build/esm/index.client.js",
+        "require": "./build/cjs/index.client.js"
+      },
+      "node": {
+        "import": "./build/esm/index.server.js",
+        "require": "./build/cjs/index.server.js"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sentry/core": "9.0.0-alpha.2",
+    "@sentry/browser": "9.0.0-alpha.2",
+    "@sentry/node": "9.0.0-alpha.2"
+  },
+  "devDependencies": {
+    "@react-router/node": "^7.1.5",
+    "react-router": "^7.1.5"
+  },
+  "peerDependencies": {
+    "@react-router/node": "7.x",
+    "react-router": "7.x",
+    "react": ">=18"
+  },
+  "scripts": {
+    "build": "run-p build:transpile build:types",
+    "build:dev": "yarn build",
+    "build:transpile": "rollup -c rollup.npm.config.mjs",
+    "build:types": "run-s build:types:core",
+    "build:types:core": "tsc -p tsconfig.types.json",
+    "build:watch": "run-p build:transpile:watch build:types:watch",
+    "build:dev:watch": "yarn build:watch",
+    "build:transpile:watch": "rollup -c rollup.npm.config.mjs --watch",
+    "build:types:watch": "tsc -p tsconfig.types.json --watch",
+    "build:tarball": "npm pack",
+    "circularDepCheck": "madge --circular src/index.client.ts && madge --circular src/index.server.ts && madge --circular src/index.types.ts",
+    "clean": "rimraf build coverage sentry-react-router-*.tgz",
+    "fix": "eslint . --format stylish --fix",
+    "lint": "eslint . --format stylish",
+    "test": "yarn test:unit",
+    "test:unit": "vitest run",
+    "test:watch": "vitest --watch",
+    "yalc:publish": "yalc publish --push --sig"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  }
+}

Diff for: packages/react-router/rollup.npm.config.mjs

@@ -0,0 +1,22 @@
+import { makeBaseNPMConfig, makeNPMConfigVariants } from '@sentry-internal/rollup-utils';
+
+export default [
+  ...makeNPMConfigVariants(
+    makeBaseNPMConfig({
+      entrypoints: ['src/index.server.ts', 'src/index.client.ts'],
+      packageSpecificConfig: {
+        external: ['react-router', 'react-router-dom', 'react', 'react/jsx-runtime'],
+        output: {
+          // make it so Rollup calms down about the fact that we're combining default and named exports
+          exports: 'named',
+        },
+      },
+      sucrase: {
+        // React 19 emits a warning if we don't use the newer jsx transform: https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html
+        // but this breaks react 17, so we keep it at `classic` for now
+        jsxRuntime: 'classic',
+        production: true, // This is needed so that sucrase uses the production jsx runtime (ie `import { jsx } from 'react/jsx-runtime'` instead of `import { jsxDEV as _jsxDEV } from 'react/jsx-dev-runtime'`)
+      },
+    }),
+  ),
+];

Diff for: packages/react-router/src/client/index.ts

@@ -0,0 +1,3 @@
+export * from '@sentry/browser';
+
+export { init } from './sdk';

Diff for: packages/react-router/src/client/sdk.ts

@@ -0,0 +1,21 @@
+import type { BrowserOptions } from '@sentry/browser';
+import { init as browserInit } from '@sentry/browser';
+import type { Client } from '@sentry/core';
+import { applySdkMetadata, setTag } from '@sentry/core';
+
+/**
+ * Initializes the client side of the React Router SDK.
+ */
+export function init(options: BrowserOptions): Client | undefined {
+  const opts = {
+    ...options,
+  };
+
+  applySdkMetadata(opts, 'react-router', ['react-router', 'browser']);
+
+  const client = browserInit(opts);
+
+  setTag('runtime', 'browser');
+
+  return client;
+}

Diff for: packages/react-router/src/common/debug-build.ts

@@ -0,0 +1,8 @@
+declare const __DEBUG_BUILD__: boolean;
+
+/**
+ * This serves as a build time flag that will be true by default, but false in non-debug builds or if users replace `__SENTRY_DEBUG__` in their generated code.
+ *
+ * ATTENTION: This constant must never cross package boundaries (i.e. be exported) to guarantee that it can be used for tree shaking.
+ */
+export const DEBUG_BUILD = __DEBUG_BUILD__;

Diff for: packages/react-router/src/index.client.ts

@@ -0,0 +1 @@
+export * from './client';

Diff for: packages/react-router/src/index.server.ts

@@ -0,0 +1 @@
+export * from './server';

Diff for: packages/react-router/src/index.types.ts

@@ -0,0 +1,16 @@
+// re-define colliding type exports below
+
+export * from './client';
+export * from './server';
+
+import type { Integration, Options, StackParser } from '@sentry/core';
+import type * as clientSdk from './client';
+import type * as serverSdk from './server';
+
+/** Initializes Sentry React Router SDK */
+export declare function init(options: Options | clientSdk.BrowserOptions | serverSdk.NodeOptions): void;
+
+export declare const contextLinesIntegration: typeof clientSdk.contextLinesIntegration;
+export declare const linkedErrorsIntegration: typeof clientSdk.linkedErrorsIntegration;
+export declare const defaultStackParser: StackParser;
+export declare const getDefaultIntegrations: (options: Options) => Integration[];

Diff for: packages/react-router/src/server/index.ts

@@ -0,0 +1,3 @@
+export * from '@sentry/node';
+
+export { init } from './sdk';

Diff for: packages/react-router/src/server/sdk.ts

@@ -0,0 +1,20 @@
+import { applySdkMetadata, setTag } from '@sentry/core';
+import type { NodeClient, NodeOptions } from '@sentry/node';
+import { init as initNodeSdk } from '@sentry/node';
+
+/**
+ * Initializes the server side of the React Router SDK
+ */
+export function init(options: NodeOptions): NodeClient | undefined {
+  const opts = {
+    ...options,
+  };
+
+  applySdkMetadata(opts, 'react-router', ['react-router', 'node']);
+
+  const client = initNodeSdk(opts);
+
+  setTag('runtime', 'node');
+
+  return client;
+}