sentry-react-sdk

All Skills > SDK Setup > React SDK

Sentry React SDK

Opinionated wizard that scans your React project and guides you through complete Sentry setup.

Invoke This Skill When

• User asks to "add Sentry to React" or "set up Sentry" in a React app
• User wants error monitoring, tracing, session replay, profiling, or logging in React
• User mentions @sentry/react, React Sentry SDK, or Sentry error boundaries
• User wants to monitor React Router v5/v6/v7 non-framework navigation, Redux state, or component performance

If project is React Router Framework mode using @sentry/react-router, use sentry-react-router-framework-sdk instead of this skill.

Note: SDK versions and APIs below reflect current Sentry docs at time of writing (@sentry/react ≥8.0.0). Always verify against docs.sentry.io/platforms/javascript/guides/react/ before implementing.

---

Phase 1: Detect

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

# Detect React version
cat package.json | grep -E '"react"|"react-dom"'

# Check for existing Sentry
cat package.json | grep '"@sentry/'

# Detect router and framework mode hints
cat package.json | grep -E '"react-router-dom"|"react-router"|"@react-router/"|"@tanstack/react-router"|"@sentry/react-router"'

# Detect state management
cat package.json | grep -E '"redux"|"@reduxjs/toolkit"'

# Detect build tool
ls vite.config.ts vite.config.js webpack.config.js craco.config.js 2>/dev/null
cat package.json | grep -E '"vite"|"react-scripts"|"webpack"'

# Detect logging libraries
cat package.json | grep -E '"pino"|"winston"|"loglevel"'

# Check for companion backend in adjacent 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
React 19+?	Use reactErrorHandler() hook pattern
React <19?	Use Sentry.ErrorBoundary
@sentry/react already present?	Skip install, go straight to feature config
React Router Framework mode indicators (@sentry/react-router, @react-router/*)?	Use sentry-react-router-framework-sdk
react-router-dom v5 / v6 / v7?	Determines which router integration to use
@tanstack/react-router?	Use tanstackRouterBrowserTracingIntegration()
Redux in use?	Recommend createReduxEnhancer()
Vite detected?	Source maps via sentryVitePlugin
CRA (react-scripts)?	Source maps via @sentry/webpack-plugin in CRACO
Backend directory found?	Trigger Phase 4 cross-link suggestion

---

Phase 2: Recommend

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

Recommended (core coverage):

• ✅ Error Monitoring — always; captures unhandled errors, React error boundaries, React 19 hooks
• ✅ Tracing — React SPAs benefit from page load, navigation, and API call tracing
• ✅ Session Replay — recommended for user-facing apps; records sessions around errors

Optional (enhanced observability):

• ⚡ Logging — structured logs via Sentry.logger.*; recommend when structured log search is needed
• ⚡ Profiling — JS Self-Profiling API (⚠️ experimental; requires cross-origin isolation headers)

Recommendation logic:

Feature	Recommend when...
Error Monitoring	Always — non-negotiable baseline
Tracing	Always for React SPAs — page load + navigation spans are high-value
Session Replay	User-facing app, login flows, or checkout pages
Logging	App needs structured log search or log-to-trace correlation
Profiling	Performance-critical app; server sends Document-Policy: js-profiling header

React-specific extras:

• React 19 detected → set up reactErrorHandler() on createRoot
• React Router v5/v6/v7 non-framework detected → configure matching router integration (see Phase 3)
• React Router Framework mode detected → switch to sentry-react-router-framework-sdk
• Redux detected → add createReduxEnhancer() to Redux store
• Vite detected → configure sentryVitePlugin for source maps (essential for readable stack traces)

Propose: "I recommend setting up Error Monitoring + Tracing + Session Replay. Want me to also add Logging or Profiling?"

---

Phase 3: Guide

Install

npm install @sentry/react --save

Create src/instrument.ts

Sentry must initialize before any other code runs. Put Sentry.init() in a dedicated sidecar file:

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

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN, // Adjust per build tool (see table below)
  environment: import.meta.env.MODE,
  release: import.meta.env.VITE_APP_VERSION, // inject at build time

  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/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },

  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],

  // Tracing
  tracesSampleRate: 1.0, // lower to 0.1–0.2 in production
  tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],

  // Session Replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  enableLogs: true,
});

DSN environment variable by build tool:

Build Tool	Variable Name	Access in code
Vite	VITE_SENTRY_DSN	import.meta.env.VITE_SENTRY_DSN
Create React App	REACT_APP_SENTRY_DSN	process.env.REACT_APP_SENTRY_DSN
Custom webpack	SENTRY_DSN	process.env.SENTRY_DSN

Entry Point Setup

Import instrument.ts as the very first import in your entry file:

// src/main.tsx (Vite) or src/index.tsx (CRA/webpack)
import "./instrument";              // ← MUST be first

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

React Version-Specific Error Handling

React 19+ — use reactErrorHandler() on createRoot:

import { reactErrorHandler } from "@sentry/react";

createRoot(document.getElementById("root")!, {
  onUncaughtError: reactErrorHandler(),
  onCaughtError: reactErrorHandler(),
  onRecoverableError: reactErrorHandler(),
}).render(<App />);

React <19 — wrap your app in Sentry.ErrorBoundary:

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

createRoot(document.getElementById("root")!).render(
  <Sentry.ErrorBoundary fallback={<p>Something went wrong</p>} showDialog>
    <App />
  </Sentry.ErrorBoundary>
);

Use <Sentry.ErrorBoundary> for any sub-tree that should catch errors independently (route sections, widgets, etc.).

Router Integration

Configure the matching integration for your router (non-framework mode):

Router	Integration	Notes
React Router v7	reactRouterV7BrowserTracingIntegration	useEffect, useLocation, useNavigationType, createRoutesFromChildren, matchRoutes from react-router
React Router v6	reactRouterV6BrowserTracingIntegration	useEffect, useLocation, useNavigationType, createRoutesFromChildren, matchRoutes from react-router-dom
React Router v5	reactRouterV5BrowserTracingIntegration	Wrap routes in withSentryRouting(Route)
TanStack Router	tanstackRouterBrowserTracingIntegration(router)	Pass router instance — no hooks required
No router / custom	browserTracingIntegration()	Names transactions by URL path

React Router v6/v7 setup:

// in instrument.ts integrations array:
import React from "react";
import {
  createRoutesFromChildren, matchRoutes,
  useLocation, useNavigationType,
} from "react-router-dom"; // or "react-router" for v7
import * as Sentry from "@sentry/react";
import { reactRouterV6BrowserTracingIntegration } from "@sentry/react";
import { createBrowserRouter } from "react-router-dom";

// Option A — createBrowserRouter (recommended for v6.4+):
const sentryCreateBrowserRouter = Sentry.wrapCreateBrowserRouterV6(createBrowserRouter);
const router = sentryCreateBrowserRouter([...routes]);

// Option B — createBrowserRouter for React Router v7:
// const sentryCreateBrowserRouter = Sentry.wrapCreateBrowserRouterV7(createBrowserRouter);

// Option C — integration with hooks (v6 without data APIs):
Sentry.init({
  integrations: [
    reactRouterV6BrowserTracingIntegration({
      useEffect: React.useEffect,
      useLocation,
      useNavigationType,
      matchRoutes,
      createRoutesFromChildren,
    }),
  ],
});

TanStack Router setup:

import { tanstackRouterBrowserTracingIntegration } from "@sentry/react";

// Pass your TanStack router instance:
Sentry.init({
  integrations: [tanstackRouterBrowserTracingIntegration(router)],
});

Redux Integration (when detected)

import * as Sentry from "@sentry/react";
import { configureStore } from "@reduxjs/toolkit";

const store = configureStore({
  reducer: rootReducer,
  enhancers: (getDefaultEnhancers) =>
    getDefaultEnhancers().concat(Sentry.createReduxEnhancer()),
});

Source Maps Setup (strongly recommended)

Without source maps, stack traces show minified code. Set up the build plugin to upload source maps automatically:

Vite (vite.config.ts):

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { sentryVitePlugin } from "@sentry/vite-plugin";

export default defineConfig({
  build: { sourcemap: "hidden" },
  plugins: [
    react(),
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

Create React App (via CRACO):

npm install @craco/craco @sentry/webpack-plugin --save-dev

// craco.config.js
const { sentryWebpackPlugin } = require("@sentry/webpack-plugin");

module.exports = {
  webpack: {
    plugins: {
      add: [
        sentryWebpackPlugin({
          org: process.env.SENTRY_ORG,
          project: process.env.SENTRY_PROJECT,
          authToken: process.env.SENTRY_AUTH_TOKEN,
        }),
      ],
    },
  },
};

SENTRY_ORG / SENTRY_PROJECT / SENTRY_AUTH_TOKEN are build-time values; the auth token is a secret (never commit it). For creating the token and wiring it into CI, see sentry-source-maps.

For Each Agreed Feature

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

Feature	Reference	Load when...
Error Monitoring	${SKILL_ROOT}/references/error-monitoring.md	Always (baseline)
Tracing	${SKILL_ROOT}/references/tracing.md	SPA navigation / API call tracing
Session Replay	${SKILL_ROOT}/references/session-replay.md	User-facing app
Logging	${SKILL_ROOT}/references/logging.md	Structured log search / log-to-trace
Profiling	${SKILL_ROOT}/references/profiling.md	Performance-critical app
React Features	${SKILL_ROOT}/references/react-features.md	Redux, component tracking, source maps, integrations catalog

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

---

Configuration Reference

Key Sentry.init() Options

Option	Type	Default	Notes
dsn	string	—	Required. SDK disabled when empty
environment	string	"production"	e.g., "staging", "development"
release	string	—	e.g., "my-app@1.0.0" or git SHA — links errors to releases
dataCollection	object	conservative unless set	Fine-grained control over auto-collected categories (userInfo, cookies, httpHeaders, httpBodies, queryParams, genAI). When omitted, the SDK falls back to sendDefaultPii (default false). Passing the object — even {} — flips unset categories to their permissive defaults; opt out per category.
tracesSampleRate	number	—	0–1; 1.0 in dev, 0.1–0.2 in prod
tracesSampler	function	—	Per-transaction sampling; overrides rate
tracePropagationTargets	(string|RegExp)[]	—	Outgoing URLs that receive distributed tracing headers
replaysSessionSampleRate	number	—	Fraction of all sessions recorded
replaysOnErrorSampleRate	number	—	Fraction of error sessions recorded
enableLogs	boolean	false	Enable Sentry.logger.* API
attachStacktrace	boolean	false	Stack traces on captureMessage() calls
maxBreadcrumbs	number	100	Breadcrumbs stored per event
debug	boolean	false	Verbose SDK output to console
tunnel	string	—	Proxy URL to bypass ad blockers

dataCollection Options (SDK ≥10.57.0)

Fine-grained control over what data the SDK collects. Collection is on by default (with sensitive-value scrubbing); opt out per category:

Field	Type	Default	Notes
userInfo	boolean	true	Collect user id, email, and IP
cookies	boolean | { allow: string[] } | { deny: string[] }	true	Cookie collection and filtering; true = all cookies (sensitive keys filtered)
httpHeaders.request	boolean | { allow: string[] } | { deny: string[] }	true	HTTP request header collection
httpHeaders.response	boolean | { allow: string[] } | { deny: string[] }	true	HTTP response header collection
queryParams	boolean | { allow: string[] } | { deny: string[] }	true	Query parameter collection and filtering
httpBodies	HttpBodyCollectionTarget[]	["incomingRequest", "outgoingRequest", "incomingResponse", "outgoingResponse"]	Collect request/response bodies; options: 'incomingRequest', 'outgoingRequest', 'incomingResponse', 'outgoingResponse'
genAI.inputs	boolean	true	Record AI model inputs (for AI monitoring)
genAI.outputs	boolean	true	Record AI model outputs (for AI monitoring)
stackFrameVariables	boolean	true	Capture local variable values in stack frames
frameContextLines	number	5	Source code context lines around stack frames

Example: Allow only specific cookies and headers:

Sentry.init({
  dataCollection: {
    cookies: { allow: ['session', 'user_id'] },
    httpHeaders: {
      request: { allow: ['authorization', 'x-request-id'] },
      response: { deny: ['set-cookie'] },
    },
  },
});

React Compatibility Matrix

React Version	Error handling approach	SDK minimum
React 19+	reactErrorHandler() on createRoot	@sentry/react ≥8.0.0
React 16–18	Sentry.ErrorBoundary component	@sentry/react ≥7.0.0
React 16	componentDidCatch class boundaries	@sentry/react ≥6.0.0

---

Verification

Trigger test events to confirm Sentry is receiving data:

// Add a temporary test button anywhere in your app
import * as Sentry from "@sentry/react";

function SentryTest() {
  return (
    <>
      <button onClick={() => { throw new Error("Sentry React test error"); }}>
        Test Error
      </button>
      <button onClick={() => Sentry.captureMessage("Sentry test message", "info")}>
        Test Message
      </button>
    </>
  );
}

Check the Sentry dashboard:

• Issues → error appears within seconds
• Traces → page load and navigation transactions visible
• Replays → session recording visible after page interaction
• Logs → structured log entries if logging enabled

Set debug: true in Sentry.init() and check the browser console if nothing appears.

---

Phase 4: Cross-Link

After completing React setup, check for a companion backend missing Sentry coverage:

ls ../backend ../server ../api ../go ../python 2>/dev/null
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3
cat ../pom.xml 2>/dev/null | grep '<artifactId>' | head -3

If a backend exists without Sentry configured, suggest the matching skill:

Backend detected	Suggest skill
Go (go.mod)	sentry-go-sdk
Python (requirements.txt, pyproject.toml)	sentry-python-sdk
Ruby (Gemfile)	sentry-ruby-sdk
Java (pom.xml, build.gradle)	Use @sentry/java — see docs.sentry.io/platforms/java/
Node.js (Express, Fastify)	Use @sentry/node — see docs.sentry.io/platforms/javascript/guides/express/

---

Troubleshooting

Issue	Solution
Events not appearing	Set debug: true, check DSN, open browser console for SDK errors
Source maps not working	Build in production mode (npm run build); verify SENTRY_AUTH_TOKEN is set
Minified stack traces	Source maps not uploading — check plugin config and auth token
instrument.ts not running first	Verify it's the first import in entry file before React/app imports
React 19 errors not captured	Confirm reactErrorHandler() is passed to all three createRoot options
React <19 errors not captured	Ensure <Sentry.ErrorBoundary> wraps the component tree
Router transactions named <unknown>	Add router integration matching your router version
tracePropagationTargets not matching	Check regex escaping; default is localhost and your DSN origin only
Session replay not recording	Confirm replayIntegration() is in init; check replaysSessionSampleRate
Redux actions not in breadcrumbs	Add Sentry.createReduxEnhancer() to store enhancers
Ad blockers dropping events	Set tunnel: "/sentry-tunnel" and add server-side relay endpoint
High replay storage costs	Lower replaysSessionSampleRate; keep replaysOnErrorSampleRate: 1.0
Profiling not working	Verify Document-Policy: js-profiling header is set on document responses