| title | Manual Setup |
|---|---|
| sidebar_order | 1 |
| description | Learn how to manually set up Sentry in your React Router v7 app and capture your first errors. |
Run the command for your preferred package manager to add the SDK package to your application:
npm install @sentry/react-router @sentry/profiling-nodeyarn add @sentry/react-router @sentry/profiling-nodepnpm add @sentry/react-router @sentry/profiling-nodeyarn add @sentry/react-routerpnpm add @sentry/react-routerChoose the features you want to configure, and this guide will show you how:
<OnboardingOptionButtons options={[ "error-monitoring", "performance", "session-replay", "user-feedback", "logs", { id: "profiling", checked: false, }, ]} />
Before configuring Sentry, you need to make React Router's entry files (entry.client.tsx and entry.server.tsx) visible in your project. Run this command to expose them:
npx react-router revealInitialize Sentry in your entry.client.tsx file:
+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___",
+
+ // Adds request headers and IP for users, for more info visit:
+ // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#sendDefaultPii
+ sendDefaultPii: true,
+
+ integrations: [
+ // ___PRODUCT_OPTION_START___ performance
+ // Registers and configures the Tracing integration,
+ // which automatically instruments your application to monitor its
+ // performance, including custom React Router routing instrumentation
+ Sentry.reactRouterTracingIntegration(),
+ // ___PRODUCT_OPTION_END___ performance
+ // ___PRODUCT_OPTION_START___ session-replay
+ // Registers the Replay integration,
+ // which automatically captures Session Replays
+ Sentry.replayIntegration(),
+ // ___PRODUCT_OPTION_END___ session-replay
+ // ___PRODUCT_OPTION_START___ user-feedback
+ Sentry.feedbackIntegration({
+ // Additional SDK configuration goes in here, for example:
+ colorScheme: "system",
+ }),
+ // ___PRODUCT_OPTION_END___ user-feedback
+ ],
+ // ___PRODUCT_OPTION_START___ logs
+
+ // Enable logs to be sent to Sentry
+ enableLogs: true,
+ // ___PRODUCT_OPTION_END___ logs
+ // ___PRODUCT_OPTION_START___ performance
+
+ // Set tracesSampleRate to 1.0 to capture 100%
+ // of transactions for tracing.
+ // We recommend adjusting this value in production
+ // Learn more at
+ // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#traces-sample-rate
+ tracesSampleRate: 1.0,
+
+ // Set `tracePropagationTargets` to declare which URL(s) should have trace propagation enabled
+ tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/],
+ // ___PRODUCT_OPTION_END___ performance
+ // ___PRODUCT_OPTION_START___ session-replay
+
+ // Capture Replay for 10% of all sessions,
+ // plus 100% of sessions with an error
+ // Learn more at
+ // https://docs.sentry.io/platforms/javascript/guides/react-router/session-replay/configuration/#general-integration-configuration
+ replaysSessionSampleRate: 0.1,
+ replaysOnErrorSampleRate: 1.0,
+ // ___PRODUCT_OPTION_END___ session-replay
+});
startTransition(() => {
hydrateRoot(
document,
<StrictMode>
<HydratedRouter onError={Sentry.sentryOnError} />
</StrictMode>
);
});The sentryOnError handler integrates with React Router's onError hook to automatically capture and report client-side errors to Sentry.
If you're on a different version, you have two options:
- Recommended: Use the Instrumentation API (React Router 7.9.5+) for automatic tracing without Node version restrictions
- Alternative: Use our manual server wrappers (shown below)
For server loaders use wrapServerLoader:
import * as Sentry from "@sentry/react-router";
export const loader = Sentry.wrapServerLoader(
{
name: "Load Some Data",
description: "Loads some data from the db",
},
async ({ params }) => {
// ... your loader logic
}
);For server actions use wrapServerAction:
import * as Sentry from "@sentry/react-router";
export const action = Sentry.wrapServerAction(
{
name: "Submit Form Data",
description: "Processes form submission data",
},
async ({ request }) => {
// ... your action logic
}
);First, create a file called instrument.server.mjs in the root of your project to initialize Sentry:
import * as Sentry from "@sentry/react-router";
// ___PRODUCT_OPTION_START___ profiling
import { nodeProfilingIntegration } from "@sentry/profiling-node";
// ___PRODUCT_OPTION_END___ profiling
Sentry.init({
dsn: "___PUBLIC_DSN___",
// Adds request headers and IP for users, for more info visit:
// https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#sendDefaultPii
sendDefaultPii: true,
// ___PRODUCT_OPTION_START___ logs
// Enable logs to be sent to Sentry
enableLogs: true,
// ___PRODUCT_OPTION_END___ logs
// ___PRODUCT_OPTION_START___ profiling
// Add our Profiling integration
integrations: [nodeProfilingIntegration()],
// ___PRODUCT_OPTION_END___ profiling
// ___PRODUCT_OPTION_START___ performance
// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for tracing.
// We recommend adjusting this value in production
// Learn more at
// https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#tracesSampleRate
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ profiling
// Enable profiling for a percentage of sessions
// Learn more at
// https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate
profileSessionSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ profiling
});Next, replace the default handleRequest and handleError functions in your entry.server.tsx file with Sentry's wrapped versions:
+import * as Sentry from '@sentry/react-router';
import { createReadableStreamFromReadable } from '@react-router/node';
import { renderToPipeableStream } from 'react-dom/server';
import { ServerRouter } from 'react-router';
import { type HandleErrorFunction } from 'react-router';
+const handleRequest = Sentry.createSentryHandleRequest({
+ ServerRouter,
+ renderToPipeableStream,
+ createReadableStreamFromReadable,
+});
export default handleRequest;
+export const handleError = Sentry.createSentryHandleError({
+ logErrors: false
+});
// ... rest of your server entryimport {
getMetaTagTransformer,
wrapSentryHandleRequest,
} from "@sentry/react-router";
// ... other imports
const handleRequest = function handleRequest(
request: Request,
responseStatusCode: number,
responseHeaders: Headers,
routerContext: EntryContext,
_loadContext: AppLoadContext
): Promise<Response> {
return new Promise((resolve, reject) => {
let shellRendered = false;
const userAgent = request.headers.get("user-agent");
// Determine if we should use onAllReady or onShellReady
const isBot = typeof userAgent === "string" && botRegex.test(userAgent);
const isSpaMode = !!(routerContext as { isSpaMode?: boolean }).isSpaMode;
const readyOption = isBot || isSpaMode ? "onAllReady" : "onShellReady";
const { pipe, abort } = renderToPipeableStream(
<ServerRouter context={routerContext} url={request.url} />,
{
[readyOption]() {
shellRendered = true;
const body = new PassThrough();
const stream = createReadableStreamFromReadable(body);
responseHeaders.set("Content-Type", "text/html");
resolve(
new Response(stream, {
headers: responseHeaders,
status: responseStatusCode,
})
);
// this enables distributed tracing between client and server
pipe(getMetaTagTransformer(body));
},
onShellError(error: unknown) {
reject(error);
},
onError(error: unknown) {
// eslint-disable-next-line no-param-reassign
responseStatusCode = 500;
// Log streaming rendering errors from inside the shell. Don't log
// errors encountered during initial shell rendering since they'll
// reject and get logged in handleDocumentRequest.
if (shellRendered) {
// eslint-disable-next-line no-console
console.error(error);
}
},
}
);
// Abort the rendering stream after the `streamTimeout`
setTimeout(abort, streamTimeout);
});
};
// wrap the default export
export default wrapSentryHandleRequest(handleRequest);
// ... rest of your entry.server.ts fileimport {
getMetaTagTransformer,
wrapSentryHandleRequest,
} from "@sentry/react-router";
// ... other imports
export function handleError(
error: unknown,
{ request, params, context }: LoaderFunctionArgs | ActionFunctionArgs
) {
if (!request.signal.aborted) {
Sentry.captureException(error);
console.error(formatErrorForJsonLogging(error));
}
}
// ... rest of your entry.server.ts fileReact Router runs in ESM mode, which means you need to load the Sentry instrumentation file before the application starts. Update your package.json scripts:
"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",
}Deploying to Vercel, Netlify, and similar platforms
If you're deploying to platforms where you can't set the NODE_OPTIONS flag, import the instrumentation file directly at the top of your entry.server.tsx:
+import './instrument.server';
import * as Sentry from '@sentry/react-router';
import { createReadableStreamFromReadable } from '@react-router/node';
import { renderToPipeableStream } from 'react-dom/server';
// ... rest of your importsWhen you import the instrumentation file directly instead of using the --import flag, automatic instrumentation will be incomplete. You'll miss automatically captured spans and traces for some server-side operations. Only use this approach when the NODE_OPTIONS method isn't available.
The stack traces in your Sentry errors probably won't look like your actual code without unminifying them. To fix this, upload your source maps to Sentry.
First, update vite.config.ts to include the sentryReactRouter plugin, making sure to pass both the Vite and Sentry configurations to it:
import { reactRouter } from '@react-router/dev/vite';
import { sentryReactRouter, type SentryReactRouterBuildOptions } from '@sentry/react-router';
import { defineConfig } from 'vite';
const sentryConfig: SentryReactRouterBuildOptions = {
org: "___ORG_SLUG___",
project: "___PROJECT_SLUG___",
// An auth token is required for uploading source maps;
// store it in an environment variable to keep it secure.
authToken: process.env.SENTRY_AUTH_TOKEN,
// ...
};
export default defineConfig(config => {
return {
+ plugins: [reactRouter(),sentryReactRouter(sentryConfig, config)],
};
});To keep your auth token secure, always store it in an environment variable instead of directly in your files:
SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___Next, include the sentryOnBuildEnd hook in react-router.config.ts:
import type { Config } from "@react-router/dev/config";
import { sentryOnBuildEnd } from "@sentry/react-router";
export default {
ssr: true,
buildEnd: async ({ viteConfig, reactRouterConfig, buildManifest }) => {
// ...
// Call this at the end of the hook
+(await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest }));
},
} satisfies Config;Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
To verify that Sentry captures errors and creates issues in your Sentry project, throw an error in a loader:
import type { Route } from "./+types/example-page";
export async function loader() {
throw new Error("My first Sentry error!");
}
export default function ExamplePage() {
return <div>Loading this page will throw an error</div>;
}import * as Sentry from "@sentry/react-router";
import type { Route } from "./+types/example-page";
export async function loader() {
return Sentry.startSpan(
{
op: "test",
name: "My First Test Transaction",
},
() => {
throw new Error("My first Sentry error!");
}
);
}
export default function ExamplePage() {
return <div>Loading this page will throw an error</div>;
}Open the route in your browser. You should start a trace and trigger an error.
Now, head over to your project on Sentry.io to view the collected data (it takes a couple of moments for the data to appear).
At this point, you should have integrated Sentry into your React Router Framework application and should already be sending data to your Sentry project.
Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:
- Learn how to manually capture errors
- Continue to customize your configuration
- Get familiar with Sentry's product features like tracing, insights, and alerts
- Find various topics in Troubleshooting
- Get support