feat(react-router): Add basic package

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

package.json

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

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'],
+};

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.

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",
+}
+```

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"
+ }
+}

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'`)
+ },
+ }),
+ ),
+];

packages/react-router/src/client/index.ts

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

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;
+}

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__;

packages/react-router/src/index.client.ts

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

packages/react-router/src/index.server.ts

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

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[];

packages/react-router/src/server/index.ts

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

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;
+}

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

package.json

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

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'],
+};

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.

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",
+}
+```

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"
+ }
+}

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'`)
+ },
+ }),
+ ),
+];

packages/react-router/src/client/index.ts

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

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;
+}

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__;

packages/react-router/src/index.client.ts

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

packages/react-router/src/index.server.ts

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

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[];

packages/react-router/src/server/index.ts

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

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;
+}

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

package.json

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

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'],
+};

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.

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",
+}
+```

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"
+ }
+}

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'`)
+ },
+ }),
+ ),
+];

packages/react-router/src/client/index.ts

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

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;
+}

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__;

packages/react-router/src/index.client.ts

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

packages/react-router/src/index.server.ts

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

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[];

packages/react-router/src/server/index.ts

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

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;
+}

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

package.json

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

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'],
+};

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.

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",
+}
+```

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"
+ }
+}

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'`)
+ },
+ }),
+ ),
+];

packages/react-router/src/client/index.ts

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

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;
+}

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__;

packages/react-router/src/index.client.ts

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

packages/react-router/src/index.server.ts

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

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[];

packages/react-router/src/server/index.ts

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

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;
+}

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

package.json

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

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'],
+};

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.

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",
+}
+```

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"
+ }
+}

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'`)
+ },
+ }),
+ ),
+];

packages/react-router/src/client/index.ts

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

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;
+}

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__;

packages/react-router/src/index.client.ts

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

packages/react-router/src/index.server.ts

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

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[];

packages/react-router/src/server/index.ts

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

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;
+}

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

package.json

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

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'],
+};

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.

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",
+}
+```

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"
+ }
+}

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'`)
+ },
+ }),
+ ),
+];

packages/react-router/src/client/index.ts

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

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;
+}

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__;

packages/react-router/src/index.client.ts

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

packages/react-router/src/index.server.ts

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

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[];

packages/react-router/src/server/index.ts

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

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;
+}

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

package.json

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

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'],
+};

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.

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",
+}
+```

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"
+ }
+}

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'`)
+ },
+ }),
+ ),
+];

packages/react-router/src/client/index.ts

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

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;
+}

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__;

packages/react-router/src/index.client.ts

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

packages/react-router/src/index.server.ts

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

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[];

packages/react-router/src/server/index.ts

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

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;
+}

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

package.json

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

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'],
+};

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.

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",
+}
+```

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"
+ }
+}

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'`)
+ },
+ }),
+ ),
+];

packages/react-router/src/client/index.ts

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

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;
+}

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__;

packages/react-router/src/index.client.ts

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

packages/react-router/src/index.server.ts

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

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[];

packages/react-router/src/server/index.ts

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

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;
+}