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:

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

>

```bash

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](#verification).

If the user skips wizard setup, continue with manual setup below.

---

Option 2: Manual Setup

Install packages

npm install @sentry/react-router --save

If profiling is needed:

npm install @sentry/profiling-node --save

Expose framework entry files

npx react-router reveal

Configure client in entry.client.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___",
  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>,
  );
});

Configure server in instrument.server.mjs

import * 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,
});

Wrap server handlers in entry.server.tsx

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:

{
  "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.

Configure source maps

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;

---

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

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

Manual tracing test

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

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:

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

Error Monitoring — Sentry React Router Framework SDK

Minimum SDK: @sentry/react-router (beta)

---

Automatic and Manual Capture

---

Client setup requirement

entry.client.tsx must include:

import * as Sentry from "@sentry/react-router";
import { HydratedRouter } from "react-router/dom";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
});

hydrateRoot(document, <HydratedRouter onError={Sentry.sentryOnError} />);

Without sentryOnError, framework-level client errors may be missed.

---

Server setup requirement

entry.server.tsx:

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,
});

---

Manual capture in custom handlers

import * as Sentry from "@sentry/react-router";

export function handleError(error: unknown, args: unknown) {
  Sentry.captureException(error);
  console.error(error);
}

For custom streaming request implementations, wrap your handler:

import { wrapSentryHandleRequest } from "@sentry/react-router";

export default wrapSentryHandleRequest(customHandleRequest);

---

Loader/action wrappers

import * as Sentry from "@sentry/react-router";

export const loader = Sentry.wrapServerLoader(
  { name: "Load Data", description: "Loads route data" },
  async () => {
    // loader logic
  },
);

export const action = Sentry.wrapServerAction(
  { name: "Submit Data", description: "Handles form submission" },
  async () => {
    // action logic
  },
);

---

Verification

Use a route loader that throws:

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

Open the route and verify the event appears in Issues.

---

Troubleshooting

Logs — Sentry React Router Framework SDK

Minimum SDK: @sentry/react-router with Logs support

---

Enable logs

Set enableLogs: true in both client and server initialization where you want log ingestion.

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  enableLogs: true,
});

---

Logging APIs

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

---

Correlation guidance

For better debugging:

1. Enable tracing with meaningful transaction names. 2. Add structured fields to logs (operation, route, tenant, requestId). 3. Keep consistent keys across client and server logs.

This improves issue/trace/log correlation in Sentry.

---

Verification

1. Emit info/warn/error logs from app code. 2. Open Logs in Sentry. 3. Filter by message/metadata and confirm ingestion.

---

Troubleshooting

Profiling — Sentry React Router Framework SDK

Minimum SDK: @sentry/react-router with @sentry/profiling-node for server profiling

---

Profiling setup (server)

Install profiling package:

npm install @sentry/profiling-node --save

Configure in instrument.server.mjs:

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

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [nodeProfilingIntegration()],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 1.0,
});

---

Sampling strategy

Start high in development, then lower for production cost control.

---

Verification

1. Trigger a server transaction with profiling enabled. 2. Open Profiles in Sentry. 3. Confirm profile entries appear and are linked to transactions.

---

Troubleshooting

React Router Framework Features — Sentry React Router Framework SDK

Framework mode package: @sentry/react-router

---

Wizard path

Use the installer for fastest setup:

npx @sentry/wizard@latest -i reactRouter

The wizard can:

• install SDK packages
• expose entry.client.tsx and entry.server.tsx
• create instrument.server.mjs
• configure source maps in Vite/React Router config
• add example verification files/routes

---

Manual framework file checklist

1. entry.client.tsx with:

• Sentry.init(...)
• HydratedRouter onError={Sentry.sentryOnError}

2. instrument.server.mjs with server Sentry.init(...) 3. entry.server.tsx with:

• createSentryHandleRequest
• createSentryHandleError

4. Runtime startup with NODE_OPTIONS='--import ./instrument.server.mjs'

---

Source maps for framework builds

Vite plugin

import { reactRouter } from "@react-router/dev/vite";
import { sentryReactRouter } from "@sentry/react-router";

export default defineConfig((config) => ({
  plugins: [reactRouter(), sentryReactRouter(sentryConfig, config)],
}));

React Router build end hook

import { sentryOnBuildEnd } from "@sentry/react-router";

export default {
  ssr: true,
  buildEnd: async ({ viteConfig, reactRouterConfig, buildManifest }) => {
    await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest });
  },
};

Auth token

Use SENTRY_AUTH_TOKEN via environment variables (or .env.sentry-build-plugin).

---

Runtime startup strategies

Preferred (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 (direct import)

If runtime flags are unavailable, import server instrumentation at the top of entry.server.tsx:

import "./instrument.server.mjs";

This fallback may have incomplete automatic instrumentation compared to --import.

---

Non-framework handoff

If project uses React Router in data/declarative mode without framework entry wrappers, route setup to sentry-react-sdk (@sentry/react) for v5/v6/v7 integrations.

---

Troubleshooting

Session Replay — Sentry React Router Framework SDK

Minimum SDK: @sentry/react-router with Replay support

---

Replay setup (client)

Configure replay in entry.client.tsx:

import * as Sentry from "@sentry/react-router";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [Sentry.replayIntegration()],
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

---

Sampling guidance

---

Privacy controls

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

---

Verification

1. Use the app in a browser and trigger an error. 2. Open Replays in Sentry. 3. Confirm replay exists and is linked to errors/traces.

---

Troubleshooting

Tracing — Sentry React Router Framework SDK

Minimum SDK: @sentry/react-router (beta)

---

Enable tracing

Configure tracing in entry.client.tsx:

import * as Sentry from "@sentry/react-router";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [Sentry.reactRouterTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
});

---

Sampling guidance

If both tracesSampleRate and tracesSampler are provided, tracesSampler takes precedence.

---

Distributed tracing

Use tracePropagationTargets so Sentry sends trace headers to your backend routes:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [Sentry.reactRouterTracingIntegration()],
  tracesSampleRate: 0.2,
  tracePropagationTargets: [/^\//, /^https:\/\/api\.example\.com/],
});

---

Custom spans

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

---

Node runtime note

Automatic server-side instrumentation compatibility has version limits for some Node versions in current docs. If your runtime is outside supported auto-instrumentation ranges, use framework instrumentation APIs or manual wrappers to keep tracing coverage.

---

Verification

1. Trigger one loader/action request from the app. 2. Open Traces in Sentry. 3. Confirm transaction names, spans, and linked errors appear.

---

Troubleshooting

User Feedback — Sentry React Router Framework SDK

Minimum SDK: @sentry/react-router with Feedback support

---

Feedback widget setup

Configure in entry.client.tsx:

import * as Sentry from "@sentry/react-router";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.feedbackIntegration({
      colorScheme: "system",
    }),
  ],
});

---

Common options

Sentry.feedbackIntegration({
  autoInject: true,
  colorScheme: "system",
  showName: true,
  showEmail: true,
  triggerLabel: "Report a bug",
  formTitle: "Report a bug",
  submitButtonLabel: "Send report",
  successMessageText: "Thanks for the report.",
});

---

Error-linked feedback dialog

const eventId = Sentry.captureException(new Error("Checkout failed"));
Sentry.showReportDialog({
  eventId,
  title: "Something went wrong",
  subtitle: "Tell us what happened",
});

---

Verification

1. Trigger feedback widget submission from the app. 2. Open User Feedback in Sentry. 3. Confirm submissions appear and error-linked reports attach to events.

---

Troubleshooting