All Skills > SDK Setup > 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: 検出

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

# React Router Framework インジケーターとバージョンを検出
cat package.json | grep -E '"react-router"|"@react-router/"|"react-router-dev"|"react-router-serve"'

# Sentry パッケージの選択を検出
cat package.json | grep -E '"@sentry/react-router"|"@sentry/react"|"@sentry/profiling-node"'

# エントリーポイントの可視性とサーバー計測ファイルをチェック
ls entry.client.tsx entry.server.tsx instrument.server.mjs react-router.config.ts vite.config.ts 2>/dev/null

# React Router ファイルがまだ隠れているかチェック (フレームワークモードヘルパーコマンド利用可)
cat package.json | grep -E '"reveal"|react-router'

# ランタイムスタートアップスクリプトとインポート戦略を検出
cat package.json | grep -E '"dev"|"start"|NODE_OPTIONS|--import'

# ロギング/プロファイル関連の任意の依存関係を検出
cat package.json | grep -E '"pino"|"winston"|"@sentry/profiling-node"'

# コンパニオンバックエンドディレクトリを検出
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 config が存在するか?	ソースマップアップロードとビルド終了フック設定パス
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___",
  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>,
  );
});

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

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	エントリーファイル、ラッパー、ソースマップ、スタートアップインポート戦略

各機能について: ${SKILL_ROOT}/references/<feature>.md を読み、ステップに従い、動作確認します。

---

設定リファレンス

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

オプション	タイプ	デフォルト	注釈
dsn	string	—	必須; 空の場合 SDK は無効
sendDefaultPii	boolean	false	ヘッダー/IP 導出ユーザーコンテキストを含める
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. アプリが実際に非フレームワークルーティング (v5/v6/v7 データ/宣言型と @sentry/react) かどうかを確認します。
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 に切り替え