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

Sentry React SDK

React プロジェクトをスキャンし、Sentry の完全セットアップをガイドする指向型ウィザード。

このスキルを呼び出すタイミング

• ユーザーが「React に Sentry を追加」または「React アプリで Sentry をセットアップ」するよう求めている
• ユーザーが React でエラーモニタリング、トレーシング、セッションリプレイ、プロファイリング、またはロギングを望んでいる
• ユーザーが @sentry/react、React Sentry SDK、または Sentry エラーバウンダリーに言及している
• ユーザーが React Router v5/v6/v7 非フレームワークナビゲーション、Redux ステート、またはコンポーネントパフォーマンスのモニタリングを望んでいる

プロジェクトが @sentry/react-router を使用する React Router フレームワークモードの場合は、このスキルの代わりに sentry-react-router-framework-sdk を使用してください。

注意: 以下の SDK バージョンと API は、執筆時点での Sentry ドキュメント (@sentry/react ≥8.0.0) を反映しています。 実装前に常に docs.sentry.io/platforms/javascript/guides/react/ で確認してください。

---

フェーズ 1: 検出

推奨を行う前に、プロジェクトを理解するために以下のコマンドを実行します:

# React バージョンを検出
cat package.json | grep -E '"react"|"react-dom"'

# 既存の Sentry を確認
cat package.json | grep '"@sentry/'

# ルーターとフレームワークモードのヒントを検出
cat package.json | grep -E '"react-router-dom"|"react-router"|"@react-router/"|"@tanstack/react-router"|"@sentry/react-router"'

# ステート管理を検出
cat package.json | grep -E '"redux"|"@reduxjs/toolkit"'

# ビルドツールを検出
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"'

# ロギングライブラリを検出
cat package.json | grep -E '"pino"|"winston"|"loglevel"'

# 隣接ディレクトリのバックエンドコンパニオンを確認
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 フレームワークモードのインジケータ (@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 には常に — ページロード + ナビゲーション span は高い価値
セッションリプレイ	ユーザー向けアプリ、ログインフロー、またはチェックアウトページ
ロギング	アプリが構造化ログ検索またはログ-トレース相関を必要とする場合
プロファイリング	パフォーマンスクリティカルなアプリ; サーバーが Document-Policy: js-profiling ヘッダーを送信

React 固有のエクストラ:

• React 19 が検出される → createRoot で reactErrorHandler() をセットアップ
• React Router v5/v6/v7 非フレームワークが検出される → マッチするルーター統合を設定 (フェーズ 3 を参照)
• React Router フレームワークモードが検出される → 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, // ビルドツールに応じて調整 (下の表を参照)
  environment: import.meta.env.MODE,
  release: import.meta.env.VITE_APP_VERSION, // ビルド時にインジェクト

  sendDefaultPii: true,

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

  // トレーシング
  tracesSampleRate: 1.0, // 本番環境では 0.1–0.2 に低下
  tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],

  // セッションリプレイ
  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 を最初のインポートとしてインポートします:

// src/main.tsx (Vite) or src/index.tsx (CRA/webpack)
import "./instrument";              // ← 必ず最初に

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	useEffect、useLocation、useNavigationType、createRoutesFromChildren、react-router の matchRoutes
React Router v6	reactRouterV6BrowserTracingIntegration	useEffect、useLocation、useNavigationType、createRoutesFromChildren、react-router-dom の matchRoutes
React Router v5	reactRouterV5BrowserTracingIntegration	ルートを withSentryRouting(Route) でラップ
TanStack Router	tanstackRouterBrowserTracingIntegration(router)	ルーターインスタンスをパス — フックは不要
ルーターなし / カスタム	browserTracingIntegration()	URL パスでトランザクション命名

React Router v6/v7 セットアップ:

// instrument.ts の integrations 配列内:
import React from "react";
import {
  createRoutesFromChildren, matchRoutes,
  useLocation, useNavigationType,
} from "react-router-dom"; // v7 の場合は "react-router"
import * as Sentry from "@sentry/react";
import { reactRouterV6BrowserTracingIntegration } from "@sentry/react";
import { createBrowserRouter } from "react-router-dom";

// オプション A — createBrowserRouter (v6.4+ 推奨):
const sentryCreateBrowserRouter = Sentry.wrapCreateBrowserRouterV6(createBrowserRouter);
const router = sentryCreateBrowserRouter([...routes]);

// オプション B — React Router v7 用 createBrowserRouter:
// const sentryCreateBrowserRouter = Sentry.wrapCreateBrowserRouterV7(createBrowserRouter);

// オプション C — フック統合 (データ API なし v6):
Sentry.init({
  integrations: [
    reactRouterV6BrowserTracingIntegration({
      useEffect: React.useEffect,
      useLocation,
      useNavigationType,
      matchRoutes,
      createRoutesFromChildren,
    }),
  ],
});

TanStack Router セットアップ:

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

// TanStack ルーターインスタンスをパス:
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,
    }),
  ],
});

.env に追加します (コミットしないこと):

SENTRY_AUTH_TOKEN=sntrys_...
SENTRY_ORG=my-org-slug
SENTRY_PROJECT=my-project-slug

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

合意した各機能について

機能を 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、コンポーネント追跡、ソースマップ、統合カタログ

各機能について: ${SKILL_ROOT}/references/<feature>.md を読む、手順に正確に従う、動作を検証します。

---

設定リファレンス

キー Sentry.init() オプション

オプション	型	デフォルト	注
dsn	string	—	必須。 空のときは SDK 無効
environment	string	"production"	例: "staging"、"development"
release	string	—	例: "my-app@1.0.0" または git SHA — エラーをリリースにリンク
sendDefaultPii	boolean	false	IP アドレスとリクエストヘッダーを含む
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	イベント単位で保存される breadcrumb
debug	boolean	false	コンソールへの冗長 SDK 出力
tunnel	string	—	広告ブロッカーをバイパスするプロキシ URL

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 がデータを受け取っていることを確認します:

// アプリ内の任意の場所に一時的なテストボタンを追加
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/app インポートの前の最初のインポートであることを確認
React 19 エラーがキャプチャされない	reactErrorHandler() が 3 つすべての createRoot オプションにパスされていることを確認
React <19 エラーがキャプチャされない	<Sentry.ErrorBoundary> がコンポーネントツリーをラップしていることを確認
ルータートランザクション名が <unknown>	ルーターバージョンに対応するルーター統合を追加
tracePropagationTargets がマッチしない	正規表現のエスケープを確認; デフォルトは localhost と DSN オリジンのみ
セッションリプレイが記録されない	replayIntegration() が init に含まれていることを確認; replaysSessionSampleRate を確認
Redux アクションが breadcrumb にない	ストア enhancer に Sentry.createReduxEnhancer() を追加
広告ブロッカーがイベントを破棄	tunnel: "/sentry-tunnel" を設定、サーバー側リレーエンドポイントを追加
リプレイストレージコストが高い	replaysSessionSampleRate を低下; replaysOnErrorSampleRate: 1.0 を維持
プロファイリングが機能しない	ドキュメントレスポンスで Document-Policy: js-profiling ヘッダーが設定されていることを確認