sentry-react-sdk

すべてのスキル > SDK のセットアップ > React SDK

Sentry React SDK

React プロジェクトをスキャンし、Sentry の完全なセットアップを案内する、意見を取り入れたウィザードです。

このスキルを使うタイミング

• ユーザーが React アプリへの「Sentry の追加」や「Sentry のセットアップ」を依頼した場合
• ユーザーが React でのエラー監視、トレーシング、セッションリプレイ、プロファイリング、またはロギングを希望している場合
• ユーザーが @sentry/react、React Sentry SDK、または Sentry のエラーバウンダリーについて言及した場合
• ユーザーが React Router v5/v6/v7 の非フレームワークモードのナビゲーション、Redux の状態、またはコンポーネントのパフォーマンスを監視したい場合

プロジェクトが @sentry/react-router を使用する React Router の Framework mode の場合は、このスキルではなく sentry-react-router-framework-sdk を使用してください。

注： 以下の SDK バージョンと API は、執筆時点の最新の Sentry ドキュメント（@sentry/react ≥8.0.0）に基づいています。 実装前に必ず docs.sentry.io/platforms/javascript/guides/react/ で確認してください。

---

フェーズ 1：検出

推奨事項を提示する前に、次のコマンドを実行してプロジェクトを把握します。

# 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

確認事項：

質問	影響
React 19 以降ですか？	reactErrorHandler() フックのパターンを使用します
React 19 未満ですか？	Sentry.ErrorBoundary を使用します
@sentry/react はすでに導入されていますか？	インストールを省略し、機能設定に進みます
React Router の Framework mode を示す要素（@sentry/react-router、@react-router/*）はありますか？	sentry-react-router-framework-sdk を使用します
react-router-dom は v5／v6／v7 のどれですか？	使用するルーターインテグレーションが決まります
@tanstack/react-router はありますか？	tanstackRouterBrowserTracingIntegration() を使用します
Redux を使用していますか？	createReduxEnhancer() を推奨します
Vite が検出されましたか？	sentryVitePlugin でソースマップを設定します
CRA（react-scripts）ですか？	CRACO の @sentry/webpack-plugin でソースマップを設定します
バックエンドのディレクトリが見つかりましたか？	フェーズ 4 で関連情報を提案します

---

フェーズ 2：推奨

確認結果に基づいて、具体的な推奨事項を提示します。自由回答形式の質問は避け、提案を先に示してください。

推奨（基本的なカバレッジ）：

• ✅ エラー監視 — 常に推奨します。未処理のエラー、React のエラーバウンダリー、React 19 のフックをキャプチャします
• ✅ トレーシング — React SPA では、ページ読み込み、ナビゲーション、API 呼び出しのトレーシングが有用です
• ✅ セッションリプレイ — ユーザー向けアプリに推奨します。エラー発生時のセッションを記録します

オプション（可観測性の強化）：

• ⚡ ロギング — Sentry.logger.* による構造化ログです。構造化ログの検索が必要な場合に推奨します
• ⚡ プロファイリング — JS Self-Profiling API を使用します（⚠️ 実験的機能です。クロスオリジン分離ヘッダーが必要です）

推奨ロジック：

機能	推奨する条件
エラー監視	常に — 必須の基本機能です
トレーシング	React SPA では常に — ページ読み込みとナビゲーションのスパンは非常に有用です
セッションリプレイ	ユーザー向けアプリ、ログインフロー、またはチェックアウトページ
ロギング	構造化ログの検索やログとトレースの相関が必要なアプリ
プロファイリング	パフォーマンスが重要なアプリ。サーバーが Document-Policy: js-profiling ヘッダーを送信する場合

React 固有の追加項目：

• React 19 が検出された場合 → createRoot に reactErrorHandler() を設定します
• React Router v5/v6/v7 の非フレームワークモードが検出された場合 → 対応するルーターインテグレーションを設定します（フェーズ 3 を参照）
• React Router の Framework mode が検出された場合 → sentry-react-router-framework-sdk に切り替えます
• Redux が検出された場合 → Redux ストアに createReduxEnhancer() を追加します
• Vite が検出された場合 → 読みやすいスタックトレースに不可欠なソースマップ用に sentryVitePlugin を設定します

次のように提案します：「エラー監視＋トレーシング＋セッションリプレイのセットアップをおすすめします。ロギングやプロファイリングも追加しましょうか？」

---

フェーズ 3：案内

インストール

npm install @sentry/react --save

src/instrument.ts を作成する

Sentry は、ほかのコードが実行される前に初期化する必要があります。専用のサイドカーファイルに Sentry.init() を記述します。

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 環境変数：

ビルドツール	変数名	コード内でのアクセス方法
Vite	VITE_SENTRY_DSN	import.meta.env.VITE_SENTRY_DSN
Create React App	REACT_APP_SENTRY_DSN	process.env.REACT_APP_SENTRY_DSN
カスタム webpack	SENTRY_DSN	process.env.SENTRY_DSN

エントリーポイントの設定

エントリーファイルで instrument.ts を最初の import として読み込みます。

// 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 のバージョンに応じたエラーハンドリング

React 19 以降 — createRoot で reactErrorHandler() を使用します。

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

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

React 19 未満 — アプリを 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>
);

独立してエラーを捕捉するサブツリー（ルートセクション、ウィジェットなど）には、<Sentry.ErrorBoundary> を使用します。

ルーターとの統合

使用するルーターに対応した統合を設定します（フレームワークモード以外）。

ルーター	統合	備考
React Router v7	reactRouterV7BrowserTracingIntegration	react-router の useEffect、useLocation、useNavigationType、createRoutesFromChildren、matchRoutes
React Router v6	reactRouterV6BrowserTracingIntegration	react-router-dom の useEffect、useLocation、useNavigationType、createRoutesFromChildren、matchRoutes
React Router v5	reactRouterV5BrowserTracingIntegration	ルートを withSentryRouting(Route) でラップします
TanStack Router	tanstackRouterBrowserTracingIntegration(router)	ルーターインスタンスを渡します。フックは不要です
ルーターなし／カスタム	browserTracingIntegration()	URL パスでトランザクションに名前を付けます

React Router v6/v7 の設定：

// 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 の設定：

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

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

Redux との統合（検出された場合）

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

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

ソースマップの設定（強く推奨）

ソースマップがない場合、スタックトレースには圧縮されたコードが表示されます。ビルドプラグインを設定し、ソースマップを自動的にアップロードします。

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（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 はビルド時の値です。認証トークンは秘密情報です（絶対にコミットしないでください）。トークンの作成方法と CI への組み込み方法については、sentry-source-maps を参照してください。

合意した各機能について

機能を1つずつ進めます。参照ファイルを読み込み、手順に従い、次に進む前に動作を確認します。

機能	参照先	読み込むタイミング
エラーモニタリング	${SKILL_ROOT}/references/error-monitoring.md	常に（ベースライン）
トレーシング	${SKILL_ROOT}/references/tracing.md	SPA のナビゲーション／API 呼び出しのトレースを行う場合
セッションリプレイ	${SKILL_ROOT}/references/session-replay.md	ユーザー向けアプリの場合
ロギング	${SKILL_ROOT}/references/logging.md	構造化ログ検索／ログとトレースの連携を行う場合
プロファイリング	${SKILL_ROOT}/references/profiling.md	パフォーマンスが重要なアプリの場合
React の機能	${SKILL_ROOT}/references/react-features.md	Redux、コンポーネント追跡、ソースマップ、統合カタログを扱う場合

機能ごとに、Read ${SKILL_ROOT}/references/<feature>.md を実行し、手順に正確に従って、動作を確認します。

---

設定リファレンス

主な Sentry.init() オプション

オプション	型	デフォルト	備考
dsn	string	—	必須です。 空の場合、SDK は無効になります
environment	string	"production"	例："staging"、"development"
release	string	—	例："[email protected]" または Git SHA — エラーをリリースに関連付けます
dataCollection	object	設定しない場合は保守的	自動収集されるカテゴリ（userInfo、cookies、httpHeaders、httpBodies、queryParams、genAI）を細かく制御します。省略すると、SDK は sendDefaultPii（デフォルトは false）にフォールバックします。このオブジェクトを渡すと（{} の場合も含む）、未設定のカテゴリは許可するデフォルトに切り替わります。カテゴリごとに無効化できます。
tracesSampleRate	number	—	0～1。開発環境では 1.0、本番環境では 0.1–0.2
tracesSampler	function	—	トランザクションごとのサンプリング。サンプルレートより優先されます
tracePropagationTargets	(string|RegExp)[]	—	分散トレーシングヘッダーを付与する送信先 URL
replaysSessionSampleRate	number	—	記録する全セッションの割合
replaysOnErrorSampleRate	number	—	記録するエラー発生セッションの割合
enableLogs	boolean	false	Sentry.logger.* API を有効にします
attachStacktrace	boolean	false	captureMessage() の呼び出しにスタックトレースを付加します
maxBreadcrumbs	number	100	イベントごとに保存するパンくずの数
debug	boolean	false	SDK の詳細な出力をコンソールに表示します
tunnel	string	—	広告ブロッカーを回避するためのプロキシ URL

dataCollection オプション（SDK ≥10.57.0）

SDK が収集するデータを細かく制御します。収集はデフォルトで有効（機密値はサニタイズされます）です。カテゴリごとに無効化できます。

フィールド	型	デフォルト	備考
userInfo	boolean	true	ユーザー ID、メールアドレス、IP アドレスを収集します
cookies	boolean | { allow: string[] } | { deny: string[] }	true	Cookie の収集とフィルタリング。true = すべての Cookie（機密キーはフィルタリングされます）
httpHeaders.request	boolean | { allow: string[] } | { deny: string[] }	true	HTTP リクエストヘッダーの収集
httpHeaders.response	boolean | { allow: string[] } | { deny: string[] }	true	HTTP レスポンスヘッダーの収集
queryParams	boolean | { allow: string[] } | { deny: string[] }	true	クエリパラメーターの収集とフィルタリング
httpBodies	HttpBodyCollectionTarget[]	["incomingRequest", "outgoingRequest", "incomingResponse", "outgoingResponse"]	リクエスト／レスポンス本文を収集します。オプション：'incomingRequest'、'outgoingRequest'、'incomingResponse'、'outgoingResponse'
genAI.inputs	boolean	true	AI モデルへの入力を記録します（AI モニタリング用）
genAI.outputs	boolean	true	AI モデルの出力を記録します（AI モニタリング用）
stackFrameVariables	boolean	true	スタックフレーム内のローカル変数の値を取得します
frameContextLines	number	5	スタックフレーム周辺のソースコードのコンテキスト行数

例： 特定の Cookie とヘッダーのみを許可します。

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

React 互換性マトリックス

React バージョン	エラー処理方法	SDK の最小バージョン
React 19+	createRoot での reactErrorHandler()	@sentry/react ≥8.0.0
React 16–18	Sentry.ErrorBoundary コンポーネント	@sentry/react ≥7.0.0
React 16	componentDidCatch クラス境界	@sentry/react ≥6.0.0

---

検証

テストイベントを発生させて、Sentry がデータを受信していることを確認します。

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

Sentry ダッシュボードを確認します。

• Issues → 数秒以内にエラーが表示されます
• Traces → ページ読み込みとナビゲーションのトランザクションが表示されます
• Replays → ページを操作した後にセッションの記録が表示されます
• Logs → ログ記録が有効な場合、構造化ログのエントリが表示されます

何も表示されない場合は、Sentry.init() で debug: true を設定し、ブラウザーのコンソールを確認してください。

---

フェーズ 4：相互リンク

React のセットアップが完了したら、Sentry の設定がない関連バックエンドがないか確認します。

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

バックエンドが見つかり、Sentry が設定されていない場合は、該当するスキルを提案します。

検出されたバックエンド	提案するスキル
Go（go.mod）	sentry-go-sdk
Python（requirements.txt、pyproject.toml）	sentry-python-sdk
Ruby（Gemfile）	sentry-ruby-sdk
Java（pom.xml、build.gradle）	@sentry/java を使用してください。詳しくは docs.sentry.io/platforms/java/ をご覧ください。
Node.js（Express、Fastify）	@sentry/node を使用してください。詳しくは docs.sentry.io/platforms/javascript/guides/express/ をご覧ください。

---

トラブルシューティング

問題	解決策
イベントが表示されない	debug: true を設定し、DSN を確認して、ブラウザーのコンソールで SDK エラーを確認します
ソースマップが機能しない	本番モードでビルドします（npm run build）。SENTRY_AUTH_TOKEN が設定されていることを確認します
圧縮されたスタックトレースが表示される	ソースマップがアップロードされていません。プラグイン設定と認証トークンを確認します
instrument.ts が最初に実行されない	エントリーファイルで、React／アプリのインポートより前に読み込まれていることを確認します
React 19 のエラーが捕捉されない	3 つすべての createRoot オプションに reactErrorHandler() が渡されていることを確認します
React <19 のエラーが捕捉されない	<Sentry.ErrorBoundary> がコンポーネントツリーを囲んでいることを確認します
ルーターのトランザクション名が <unknown> になる	使用しているルーターのバージョンに対応するルーター統合を追加します
tracePropagationTargets が一致しない	正規表現のエスケープを確認します。デフォルトは localhost と DSN のオリジンのみです
セッションリプレイが記録されない	replayIntegration() が初期化処理に含まれていることを確認し、replaysSessionSampleRate を確認します
Redux のアクションがブレッドクラムに表示されない	ストアのエンハンサーに Sentry.createReduxEnhancer() を追加します
広告ブロッカーによってイベントが破棄される	tunnel: "/sentry-tunnel" を設定し、サーバー側のリレーエンドポイントを追加します
リプレイのストレージコストが高い	replaysSessionSampleRate を下げ、replaysOnErrorSampleRate: 1.0 は維持します
プロファイリングが機能しない	ドキュメントのレスポンスに Document-Policy: js-profiling ヘッダーが設定されていることを確認します