Sentry React Router Framework Sdk

All Skills > SDK Setup > React Router Framework SDK

Sentry 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.

Invoke This Skill When

• User asks to "add Sentry to React Router Framework" or "set up Sentry in React Router v7 framework mode"
• User wants to install or configure @sentry/react-router
• User uses React Router framework entry files (entry.client.tsx, entry.server.tsx) and wants tracing/error capture
• User asks about reactRouterTracingIntegration, sentryOnError, createSentryHandleRequest, or React Router wizard setup

Important: This SDK is currently beta. For React Router non-framework/data/declarative mode (v5/v6/v7), use sentry-react-sdk with @sentry/react integrations instead.

Phase 1: Detect

Run these commands to understand the project before making any recommendations:

bashCopy code
# 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:

Phase 2: Recommend

Present a concrete recommendation based on what you found. Do not ask open-ended questions — lead with a proposal:

Recommended (core coverage):

• ✅ Error Monitoring — always; captures client and server errors with framework hooks
• ✅ Tracing — recommended baseline in framework apps with client/server request flow
• ✅ Session Replay — recommended for user-facing applications

Optional (enhanced observability):

• ⚡ Profiling — server-side profiling with @sentry/profiling-node
• ⚡ Logs — structured Sentry.logger.* ingestion and correlation
• ⚡ User Feedback — in-app feedback widget/reporting flows

Recommendation logic:

Propose: "I recommend Error Monitoring + Tracing + Session Replay first. Want me to also enable Profiling, Logs, and User Feedback?"

Phase 3: Guide

Option 1: Wizard (Recommended)

You need to run this yourself — the wizard is interactive and may require browser login:

bashCopy code
npx @sentry/wizard@latest -i reactRouter

It 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.

Option 2: Manual Setup

Install packages

bashCopy code
npm install @sentry/react-router --save

If profiling is needed:

bashCopy code
npm install @sentry/profiling-node --save

Expose framework entry files

bashCopy code
npx react-router reveal

Configure client in entry.client.tsx

tsxCopy code
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___",
  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  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>,
  );
});

Configure server in instrument.server.mjs

javascriptCopy code
import * as Sentry from "@sentry/react-router";
import { nodeProfilingIntegration } from "@sentry/profiling-node";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  enableLogs: true,
  integrations: [nodeProfilingIntegration()],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 1.0,
});

Wrap server handlers in entry.server.tsx

tsxCopy code
import * 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.

Load server instrumentation on startup

Prefer NODE_OPTIONS --import:

jsonCopy code
{
  "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:

tsxCopy code
import "./instrument.server.mjs";

This direct-import method can result in incomplete auto-instrumentation compared to --import.

Configure source maps

vite.config.ts:

typescriptCopy code
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:

typescriptCopy code
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;

For Each Agreed Feature

Walk through features one at a time. Load the reference file, follow steps exactly, and verify before moving on:

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

Configuration Reference

Key Sentry.init() options

Framework-specific APIs

Verification

Wizard-generated path

If wizard examples were generated, open /sentry-example-page and trigger test actions.

Manual error test

tsxCopy code
export async function loader() {
  throw new Error("My first Sentry error!");
}

Manual tracing test

tsxCopy code
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!");
    },
  );
}

Logs test

javascriptCopy code
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:

• Issues: errors appear
• Traces: transaction/span data appears
• Profiles: profiles appear when profiling enabled
• Replays: replay entries appear when enabled
• Logs: log events appear when enableLogs: true
• User Feedback: submissions appear when feedback enabled

Phase 4: Cross-Link

After completing React Router Framework setup:

1. Check whether the app is actually non-framework routing (v5/v6/v7 data/declarative with @sentry/react).
2. If yes, redirect to sentry-react-sdk for non-framework routing integrations.

Then check companion backend coverage:

bashCopy code
ls ../backend ../server ../api ../go ../python 2>/dev/null
cat ../go.mod ../requirements.txt ../pyproject.toml ../Gemfile ../pom.xml 2>/dev/null | head -5

Troubleshooting