From sentry
Sets up full Sentry SDK for React Router v7 Framework mode, installing @sentry/react-router and configuring error monitoring, tracing, profiling, session replay, logs, user feedback in client/server entry points.
npx claudepluginhub getsentry/sentry-for-ai --plugin sentryThis skill uses the workspace's default tool permissions.
> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > React Router Framework SDK
Sets up full Sentry SDK in React apps for error monitoring, tracing, session replay, profiling, and logging. Supports React 16+, React Router v5-v7 non-framework, TanStack Router, Redux, Vite, webpack.
Sets up full Sentry SDK in React apps for error monitoring, tracing, session replay, profiling, and logging. Supports React 16+, React Router v5-7, TanStack Router, Redux, Vite, webpack.
Guides Sentry SDK selection and setup for error tracking, performance monitoring in monoliths, microservices, serverless, event-driven, SPAs, mobile, and hybrid architectures.
Share bugs, ideas, or general feedback.
All Skills > SDK Setup > React Router Framework SDK
Opinionated wizard that scans your React Router Framework project and guides you through complete Sentry setup across client and server entry points.
@sentry/react-routerentry.client.tsx, entry.server.tsx) and wants tracing/error capturereactRouterTracingIntegration, sentryOnError, createSentryHandleRequest, or React Router wizard setupImportant: This SDK is currently beta. For React Router non-framework/data/declarative mode (v5/v6/v7), use
sentry-react-sdkwith@sentry/reactintegrations instead.
Run these commands to understand the project before making any recommendations:
# Detect React Router Framework indicators and versions
cat package.json | grep -E '"react-router"|"@react-router/"|"react-router-dev"|"react-router-serve"'
# Detect Sentry package choice
cat package.json | grep -E '"@sentry/react-router"|"@sentry/react"|"@sentry/profiling-node"'
# Check entry point visibility and server instrumentation files
ls entry.client.tsx entry.server.tsx instrument.server.mjs react-router.config.ts vite.config.ts 2>/dev/null
# Check if React Router files are still hidden (framework mode helper command available)
cat package.json | grep -E '"reveal"|react-router'
# Detect runtime startup scripts and import strategy
cat package.json | grep -E '"dev"|"start"|NODE_OPTIONS|--import'
# Detect optional logging/profile-related dependencies
cat package.json | grep -E '"pino"|"winston"|"@sentry/profiling-node"'
# Detect companion backend directories
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile ../pom.xml 2>/dev/null | head -3
What to determine:
| Question | Impact |
|---|---|
@sentry/react-router already installed? | Skip install and move to feature setup |
| Framework entry files exposed? | Need npx react-router reveal before manual config |
Using @sentry/react instead? | This is likely non-framework routing; redirect to sentry-react-sdk |
react-router.config.ts + Vite config present? | Source map upload and build-end hook setup path |
NODE_OPTIONS --import available? | Preferred server instrumentation startup path |
@sentry/profiling-node desired/available? | Enable server profiling integration |
| Backend directory found? | Trigger Phase 4 cross-link suggestion |
Present a concrete recommendation based on what you found. Do not ask open-ended questions — lead with a proposal:
Recommended (core coverage):
Optional (enhanced observability):
@sentry/profiling-nodeSentry.logger.* ingestion and correlationRecommendation logic:
| Feature | Recommend when... |
|---|---|
| Error Monitoring | Always — non-negotiable baseline |
| Tracing | Usually yes in framework apps; route and request timing is high-value |
| Session Replay | User-facing product or difficult UX debugging |
| Profiling | Server performance investigations needed; Node runtime compatibility verified |
| Logs | Team wants log-search and trace correlation in Sentry |
| User Feedback | Product/support teams need direct in-app issue reports |
Propose: "I recommend Error Monitoring + Tracing + Session Replay first. Want me to also enable Profiling, Logs, and User Feedback?"
You need to run this yourself — the wizard is interactive and may require browser login:
npx @sentry/wizard@latest -i reactRouterIt installs
@sentry/react-router, exposes React Router entry files, creates instrumentation files, updates root error handling, configures source map upload, and adds verification examples.Once it finishes, continue at Verification.
If the user skips wizard setup, continue with manual setup below.
npm install @sentry/react-router --save
If profiling is needed:
npm install @sentry/profiling-node --save
npx react-router reveal
entry.client.tsximport * 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___",
sendDefaultPii: true,
integrations: [
Sentry.reactRouterTracingIntegration(),
Sentry.replayIntegration(),
Sentry.feedbackIntegration({ colorScheme: "system" }),
],
enableLogs: true,
tracesSampleRate: 1.0,
tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/],
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
});
startTransition(() => {
hydrateRoot(
document,
<StrictMode>
<HydratedRouter onError={Sentry.sentryOnError} />
</StrictMode>,
);
});
instrument.server.mjsimport * as Sentry from "@sentry/react-router";
import { nodeProfilingIntegration } from "@sentry/profiling-node";
Sentry.init({
dsn: "___PUBLIC_DSN___",
sendDefaultPii: true,
enableLogs: true,
integrations: [nodeProfilingIntegration()],
tracesSampleRate: 1.0,
profileSessionSampleRate: 1.0,
});
entry.server.tsximport * as Sentry from "@sentry/react-router";
import { createReadableStreamFromReadable } from "@react-router/node";
import { renderToPipeableStream } from "react-dom/server";
import { ServerRouter } from "react-router";
const handleRequest = Sentry.createSentryHandleRequest({
ServerRouter,
renderToPipeableStream,
createReadableStreamFromReadable,
});
export default handleRequest;
export const handleError = Sentry.createSentryHandleError({
logErrors: false,
});
For custom server logic, use wrapSentryHandleRequest, getMetaTagTransformer, and manual Sentry.captureException in your custom handleError.
Prefer NODE_OPTIONS --import:
{
"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"
}
}
Fallback for platforms where runtime flags are restricted:
import "./instrument.server.mjs";
This direct-import method can result in incomplete auto-instrumentation compared to --import.
vite.config.ts:
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___",
authToken: process.env.SENTRY_AUTH_TOKEN,
};
export default defineConfig((config) => {
return {
plugins: [reactRouter(), sentryReactRouter(sentryConfig, config)],
};
});
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 }) => {
await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest });
},
} satisfies Config;
Walk through features one at a time. Load the reference file, follow steps exactly, and verify before moving on:
| Feature | Reference | Load when... |
|---|---|---|
| Error Monitoring | ${SKILL_ROOT}/references/error-monitoring.md | Always |
| Tracing | ${SKILL_ROOT}/references/tracing.md | Route/request performance visibility needed |
| Profiling | ${SKILL_ROOT}/references/profiling.md | Server performance analysis needed |
| Session Replay | ${SKILL_ROOT}/references/session-replay.md | User-facing app |
| Logs | ${SKILL_ROOT}/references/logging.md | Structured logs/correlation needed |
| User Feedback | ${SKILL_ROOT}/references/user-feedback.md | In-app feedback flows needed |
| Framework Features | ${SKILL_ROOT}/references/react-router-framework-features.md | Entry files, wrappers, source maps, startup import strategy |
For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.
Sentry.init() options| Option | Type | Default | Notes |
|---|---|---|---|
dsn | string | — | Required; SDK disabled when empty |
sendDefaultPii | boolean | false | Includes headers/IP-derived user context |
integrations | Integration[] | SDK defaults | Add tracing/replay/feedback/profiling integrations |
enableLogs | boolean | false | Enables Sentry.logger.* ingestion |
tracesSampleRate | number | — | Usually 1.0 in testing, lower in production |
tracePropagationTargets | `(string | RegExp)[]` | SDK defaults |
replaysSessionSampleRate | number | — | Fraction of all sessions recorded |
replaysOnErrorSampleRate | number | — | Fraction of error sessions recorded |
profileSessionSampleRate | number | — | Fraction of transactions profiled (server profiling) |
tunnel | string | — | Optional ad-blocker bypass endpoint |
debug | boolean | false | Verbose SDK diagnostics |
| API | Purpose |
|---|---|
reactRouterTracingIntegration() | Client-side tracing integration for framework mode |
sentryOnError | Hooks into React Router HydratedRouter error reporting |
createSentryHandleRequest(...) | Server request wrapper for framework entry server |
createSentryHandleError(...) | Server error handler wrapper |
wrapServerLoader(...) / wrapServerAction(...) | Manual wrapping for server loaders/actions |
sentryReactRouter(...) | Vite plugin for source maps/build integration |
sentryOnBuildEnd(...) | React Router build-end hook for source map processing |
If wizard examples were generated, open /sentry-example-page and trigger test actions.
export async function loader() {
throw new Error("My first Sentry error!");
}
import * as Sentry from "@sentry/react-router";
export async function loader() {
return Sentry.startSpan(
{ op: "test", name: "My First Test Transaction" },
() => {
throw new Error("My first Sentry error!");
},
);
}
Sentry.logger.info("User example action completed");
Sentry.logger.warn("Slow operation detected", { operation: "data_fetch", duration: 3500 });
Sentry.logger.error("Validation failed", { field: "email", reason: "Invalid email" });
Confirm in Sentry:
enableLogs: trueAfter completing React Router Framework setup:
@sentry/react).sentry-react-sdk for non-framework routing integrations.Then check companion backend coverage:
ls ../backend ../server ../api ../go ../python 2>/dev/null
cat ../go.mod ../requirements.txt ../pyproject.toml ../Gemfile ../pom.xml 2>/dev/null | head -5
| Backend detected | Suggest skill |
|---|---|
| Go | sentry-go-sdk |
| Python | sentry-python-sdk |
| Ruby | sentry-ruby-sdk |
| Node backend services | sentry-node-sdk |
| Java services | Use @sentry/java docs |
| Issue | Solution |
|---|---|
entry.client.tsx / entry.server.tsx missing | Run npx react-router reveal first |
| Client errors missing | Ensure HydratedRouter includes onError={Sentry.sentryOnError} |
| Server errors missing | Use createSentryHandleRequest and createSentryHandleError wrappers |
| Custom server handlers bypass Sentry | Use wrapSentryHandleRequest and manual captureException in custom handleError |
| Source maps not uploaded | Verify sentryReactRouter plugin config and sentryOnBuildEnd hook |
SENTRY_AUTH_TOKEN undefined in Vite config | Load env vars in config or use .env.sentry-build-plugin |
| Incomplete server auto-instrumentation | Prefer NODE_OPTIONS='--import ./instrument.server.mjs' startup |
| Profiling data missing | Confirm @sentry/profiling-node installed and nodeProfilingIntegration enabled |
| Running unsupported Node auto-instrumentation version | Use instrumentation API/manual wrappers as documented |
Non-framework app configured with @sentry/react-router | Switch to sentry-react-sdk + @sentry/react for v5/v6/v7 non-framework routes |