sentry-react-router-framework-sdk

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

Sentry React Router Framework SDK

React Router Framework プロジェクトをスキャンし、クライアントとサーバーのエントリーポイント全体にわたる Sentry のセットアップを案内する、実用的なウィザードです。

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

• ユーザーが「React Router Framework に Sentry を追加して」または「React Router v7 のフレームワークモードで Sentry をセットアップして」と依頼した場合
• ユーザーが @sentry/react-router のインストールまたは設定を希望している場合
• ユーザーが React Router のフレームワークエントリーファイル（entry.client.tsx、entry.server.tsx）を使用しており、トレーシング／エラー取得を希望している場合
• ユーザーが reactRouterTracingIntegration、sentryOnError、createSentryHandleRequest、または React Router ウィザードのセットアップについて質問した場合

重要： この SDK は現在ベータ版です。 React Router の非フレームワーク／データ／宣言型モード（v5／v6／v7）では、@sentry/react のインテグレーションとともに sentry-react-sdk を使用してください。

---

フェーズ 1：検出

推奨事項を提示する前に、次のコマンドを実行してプロジェクトの状況を確認してください。

# 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

確認する項目：

質問	影響
@sentry/react-router はすでにインストールされていますか？	インストールをスキップし、機能のセットアップに進みます
フレームワークのエントリーファイルが公開されていますか？	手動設定の前に npx react-router reveal が必要です
代わりに @sentry/react を使用していますか？	非フレームワークのルーティングである可能性が高いため、sentry-react-sdk に案内します
react-router.config.ts と Vite の設定ファイルがありますか？	ソースマップのアップロードとビルド終了時のフックを設定する経路です
NODE_OPTIONS --import を利用できますか？	サーバーのインストルメンテーションを起動する際の推奨経路です
@sentry/profiling-node を使用する予定、または利用可能ですか？	サーバーのプロファイリングインテグレーションを有効にします
バックエンドのディレクトリが見つかりましたか？	フェーズ 4 の関連付けの提案につなげます

---

フェーズ 2：推奨

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

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

• ✅ エラーモニタリング — 常に有効にします。フレームワークのフックを使って、クライアントとサーバーのエラーを取得します
• ✅ トレーシング — クライアント／サーバーのリクエストフローがあるフレームワークアプリでは、ベースラインとして推奨します
• ✅ セッションリプレイ — ユーザー向けアプリケーションでは推奨します

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

• ⚡ プロファイリング — @sentry/profiling-node によるサーバーサイドのプロファイリングです
• ⚡ ログ — 構造化された Sentry.logger.* の取り込みと相関付けです
• ⚡ ユーザーフィードバック — アプリ内フィードバックウィジェット／報告フローです

推奨の判断基準：

機能	推奨する条件
エラーモニタリング	常に — 必須のベースラインです
トレーシング	フレームワークアプリでは通常は有効です。ルートとリクエストのタイミングは大きな価値があります
セッションリプレイ	ユーザー向けの製品、または難しい UX のデバッグが必要な場合
プロファイリング	サーバーのパフォーマンス調査が必要で、Node ランタイムとの互換性が確認できている場合
ログ	Sentry でログ検索とトレースの相関付けを行いたいチーム
ユーザーフィードバック	製品／サポートチームがアプリ内で直接問題の報告を受けたい場合

次のように提案します：「まずはエラーモニタリング＋トレーシング＋セッションリプレイをおすすめします。プロファイリング、ログ、ユーザーフィードバックも有効にしますか？」

---

フェーズ 3：案内

オプション 1：ウィザード（推奨）

この操作はご自身で実行してください — ウィザードは対話形式で、ブラウザーでのログインが必要になる場合があります。

npx @sentry/wizard@latest -i reactRouter

@sentry/react-router をインストールし、React Router のエントリーファイルを公開して、インストルメンテーションファイルを作成します。また、ルートのエラー処理を更新し、ソースマップのアップロードを設定して、検証用の例を追加します。

完了したら、検証に進んでください。

ユーザーがウィザードによるセットアップをスキップした場合は、以下の手動セットアップに進みます。

---

オプション 2：手動セットアップ

パッケージをインストールする

npm install @sentry/react-router --save

プロファイリングが必要な場合：

npm install @sentry/profiling-node --save

フレームワークのエントリーファイルを公開する

npx react-router reveal

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

instrument.server.mjs でサーバーを設定する

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

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

カスタムサーバーロジックには、wrapSentryHandleRequest、getMetaTagTransformer、およびカスタムの handleError 内での手動の Sentry.captureException を使用してください。

起動時にサーバーの計装を読み込む

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"
  }
}

ランタイムフラグが制限されているプラットフォームでの代替方法：

import "./instrument.server.mjs";

この直接インポート方式では、--import と比べて自動計装が不完全になる可能性があります。

ソースマップを設定する

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;

---

合意した各機能について

機能を1つずつ順に確認します。参照ファイルを読み込み、手順に正確に従い、次に進む前に検証してください。

機能	参照先	読み込むタイミング
エラーモニタリング	${SKILL_ROOT}/references/error-monitoring.md	常に
トレーシング	${SKILL_ROOT}/references/tracing.md	ルート／リクエストのパフォーマンスを可視化する必要がある場合
プロファイリング	${SKILL_ROOT}/references/profiling.md	サーバーのパフォーマンス分析が必要な場合
セッションリプレイ	${SKILL_ROOT}/references/session-replay.md	ユーザー向けアプリの場合
ログ	${SKILL_ROOT}/references/logging.md	構造化ログ／相関付けが必要な場合
ユーザーフィードバック	${SKILL_ROOT}/references/user-feedback.md	アプリ内のフィードバックフローが必要な場合
フレームワーク機能	${SKILL_ROOT}/references/react-router-framework-features.md	エントリーファイル、ラッパー、ソースマップ、起動時のインポート方式を扱う場合

各機能について：Read ${SKILL_ROOT}/references/<feature>.md を実行し、手順に正確に従って、動作を検証してください。

---

設定リファレンス

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

オプション	型	デフォルト	備考
dsn	string	—	必須。空の場合、SDK は無効になります
dataCollection	object	—	収集するデータ（userInfo、cookies、httpHeaders など）を制御します
dataCollection.userInfo	boolean	true	IP アドレスから推定されるユーザーコンテキストを含めます
dataCollection.cookies	CollectBehavior	true	Cookie の収集とフィルタリングを制御します
dataCollection.httpHeaders	object	{ request: true, response: true }	HTTP ヘッダーの収集を制御します
sendDefaultPii	boolean	false	非推奨： 代わりに dataCollection を使用してください。v11 で削除されます
integrations	Integration[]	SDK のデフォルト	トレーシング／リプレイ／フィードバック／プロファイリングのインテグレーションを追加します
enableLogs	boolean	false	Sentry.logger.* による取り込みを有効にします
tracesSampleRate	number	—	通常、テストでは 1.0、本番環境ではそれより低い値を設定します
tracePropagationTargets	`(string	RegExp)[]`	SDK のデフォルト
replaysSessionSampleRate	number	—	記録する全セッションの割合
replaysOnErrorSampleRate	number	—	記録するエラー発生セッションの割合
profileSessionSampleRate	number	—	プロファイリングするトランザクションの割合（サーバーのプロファイリング）
tunnel	string	—	オプションの広告ブロッカー回避用エンドポイント
debug	boolean	false	詳細な SDK 診断情報

フレームワーク固有の API

API	目的
reactRouterTracingIntegration()	フレームワークモード用のクライアント側トレーシングインテグレーション
sentryOnError	React Router の HydratedRouter によるエラー報告にフックします
createSentryHandleRequest(...)	フレームワークのエントリーサーバー用サーバーリクエストラッパー
createSentryHandleError(...)	サーバーエラーハンドラーラッパー
wrapServerLoader(...) / wrapServerAction(...)	サーバーローダー／アクションを手動でラップします
sentryReactRouter(...)	ソースマップ／ビルド連携用の Vite プラグイン
sentryOnBuildEnd(...)	ソースマップ処理用の React Router ビルド終了時フック

---

検証

ウィザードで生成されたパス

ウィザードのサンプルが生成されている場合は、/sentry-example-page を開き、テスト操作を実行してください。

手動でのエラーテスト

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

手動でのトレーシングテスト

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

ログのテスト

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

Sentry で次の項目を確認します：

• Issues：エラーが表示される
• Traces：トランザクション／スパンのデータが表示される
• Profiles：プロファイリングを有効にしている場合、プロファイルが表示される
• Replays：有効にしている場合、リプレイのエントリが表示される
• Logs：enableLogs: true の場合、ログイベントが表示される
• User Feedback：フィードバックを有効にしている場合、送信内容が表示される

---

フェーズ 4：連携先の案内

React Router Framework のセットアップが完了したら：

1. アプリが実際には非フレームワークのルーティング（@sentry/react を使用する v5／v6／v7 のデータルーティング／宣言的ルーティング）かどうかを確認します。
2. 該当する場合は、非フレームワークのルーティング連携について sentry-react-sdk に案内します。

続いて、連携するバックエンドの対応状況を確認します：

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

検出されたバックエンド	推奨するスキル
Go	sentry-go-sdk
Python	sentry-python-sdk
Ruby	sentry-ruby-sdk
Node バックエンドサービス	sentry-node-sdk
Java サービス	@sentry/java のドキュメントを使用

---

トラブルシューティング

問題	解決策
entry.client.tsx／entry.server.tsx が見つからない	まず npx react-router reveal を実行します
クライアントのエラーが見つからない	HydratedRouter に onError={Sentry.sentryOnError} が含まれていることを確認します
サーバーのエラーが見つからない	createSentryHandleRequest と createSentryHandleError のラッパーを使用します
カスタムサーバーハンドラーが Sentry を迂回する	wrapSentryHandleRequest を使用し、カスタム handleError で手動で captureException を呼び出します
ソースマップがアップロードされない	sentryReactRouter プラグインの設定と sentryOnBuildEnd フックを確認します
Vite の設定で SENTRY_AUTH_TOKEN が未定義	設定内で環境変数を読み込むか、.env.sentry-build-plugin を使用します
サーバーの自動計装が不完全	起動時に NODE_OPTIONS='--import ./instrument.server.mjs' を使用することを推奨します
プロファイリングデータが見つからない	@sentry/profiling-node がインストールされ、nodeProfilingIntegration が有効であることを確認します
サポート対象外の Node 自動計装バージョンを実行している	ドキュメントに記載されている計装 API／手動ラッパーを使用します
非フレームワークアプリで @sentry/react-router を設定している	非フレームワークの v5／v6／v7 ルートでは、sentry-react-sdk と @sentry/react に切り替えます