sentry-tanstack-start-sdk

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

Sentry TanStack Start React SDK

TanStack Start React プロジェクトをスキャンし、ブラウザーとサーバーのランタイム向けに Sentry を完全にセットアップできるよう案内する、推奨設定付きウィザードです。

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

• ユーザーが TanStack Start React アプリへの「Sentry の追加」や「Sentry のセットアップ」を求めている
• ユーザーが @sentry/tanstackstart-react のインストールや設定を希望している
• ユーザーが TanStack Start React のエラー監視、トレーシング、セッションリプレイ、ログ、ユーザーフィードバックを希望している
• ユーザーが sentryTanstackStart、wrapFetchWithSentry、instrument.server.mjs、または TanStack Start ミドルウェアの計装について質問している

注： この SDK は現在アルファ版であり、TanStack Start 1.0 RC との互換性があると記載されています。 実装前に、必ず docs.sentry.io/platforms/javascript/guides/tanstackstart-react/ で確認してください。

---

フェーズ 1：検出

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

# Detect TanStack Start / Router and existing Sentry
cat package.json | grep -E '"@tanstack/react-start"|"@tanstack/react-router"|"@sentry/tanstackstart-react"'

# Check if Sentry is already present
cat package.json | grep '"@sentry/'

# Detect key files used by the TanStack Start setup
ls src/router.tsx src/start.ts src/server.ts instrument.server.mjs vite.config.ts vite.config.js 2>/dev/null

# Check whether source map upload credentials are configured
cat .env .env.local .env.sentry-build-plugin 2>/dev/null | grep "SENTRY_AUTH_TOKEN"

# Detect deployment hints in scripts
cat package.json | grep -E '"dev"|"build"|"start"|NODE_OPTIONS|--import'

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

# Detect companion backend directories
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile ../pom.xml 2>/dev/null | head -3

確認する項目：

質問	影響
@tanstack/react-start が存在するか？	このスキルが適切なセットアップ手順であることを確認します
@sentry/tanstackstart-react がすでにインストールされているか？	インストールを省略し、機能の調整に進みます
src/router.tsx が存在するか？	クライアント側の Sentry.init の配置先を確認します
src/start.ts が存在するか？	サーバー側エラー向けのグローバルミドルウェアの設定先を確認します
src/server.ts が存在するか？	サーバーエントリーの計装の配置先を確認します
instrument.server.mjs が存在するか？	ランタイム起動時の計装方法を確認します
vite.config.ts が存在するか？	sentryTanstackStart プラグインとソースマップの追加先を確認します
SENTRY_AUTH_TOKEN が設定されているか？	ソースマップをアップロードできる状態か確認します
バックエンドのディレクトリが見つかったか？	フェーズ 4 の関連リンクの提案を促します

---

フェーズ 2：推奨事項の提示

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

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

• ✅ エラー監視 — 常に有効にします。未処理のクライアント側およびサーバー側のエラーを取得します
• ✅ トレーシング — ブラウザーとサーバーをまたいだリクエストおよびルートの処理時間を把握するのに役立ちます
• ✅ セッションリプレイ — ユーザー向けアプリに推奨します

オプション（監視機能の強化）：

• ⚡ ログ — 構造化ログの検索や、ログとトレースの関連付けが必要な場合に推奨します
• ⚡ ユーザーフィードバック — プロダクトチームがアプリ内での問題報告を希望する場合に推奨します

推奨ロジック：

機能	次の場合に推奨します…
エラー監視	常に — 妥協できない基本要件です
トレーシング	TanStack Start では通常は有効にします。ルートと fetch の計装により、すぐに効果が得られます
セッションリプレイ	ユーザー向けアプリ、ログインフロー、チェックアウトフロー、または再現が難しい UX の不具合がある場合
ログ	既存のロギング方針、サポートのワークフロー、またはトレースとログの関連付けが必要な場合
ユーザーフィードバック	アプリを離れずにユーザーから直接報告を受けたい場合

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

---

フェーズ 3：案内

インストール

npm install @sentry/tanstackstart-react --save

src/router.tsx でクライアント側の Sentry を設定する

ルーターのファクトリー内で Sentry を初期化し、ブラウザーでのみ実行されるようにします。

import * as Sentry from "@sentry/tanstackstart-react";
import { createRouter } from "@tanstack/react-router";

export const getRouter = () => {
  const router = createRouter();

  if (!router.isServer) {
    Sentry.init({
      dsn: "___PUBLIC_DSN___",
      dataCollection: {
        // userInfo: false,
        // httpBodies: [],
      },

      integrations: [
        Sentry.tanstackRouterBrowserTracingIntegration(router),
        Sentry.replayIntegration(),
        Sentry.feedbackIntegration({
          colorScheme: "system",
        }),
      ],

      enableLogs: true,
      tracesSampleRate: 1.0,
      replaysSessionSampleRate: 0.1,
      replaysOnErrorSampleRate: 1.0,
    });
  }

  return router;
};

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

プロジェクトのルートに instrument.server.mjs を作成します。

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

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/tanstackstart-react/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  enableLogs: true,
  tracesSampleRate: 1.0,
});

vite.config.ts で Vite プラグインを設定する

sentryTanstackStart は最後のプラグインにしてください。

import { defineConfig } from "vite";
import { sentryTanstackStart } from "@sentry/tanstackstart-react/vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";

export default defineConfig({
  plugins: [
    tanstackStart(),
    sentryTanstackStart({
      org: "___ORG_SLUG___",
      project: "___PROJECT_SLUG___",
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

トークンが .env に保存されている場合は、プラグインに渡す前に Vite の設定で loadEnv を使って読み込みます。

src/server.ts でサーバーのエントリーポイントを計装する

fetch ハンドラーを wrapFetchWithSentry でラップします。

import { wrapFetchWithSentry } from "@sentry/tanstackstart-react";
import handler, { createServerEntry } from "@tanstack/react-start/server-entry";

export default createServerEntry(
  wrapFetchWithSentry({
    fetch(request: Request) {
      return handler.fetch(request);
    },
  }),
);

src/start.ts にグローバルサーバーミドルウェアを追加する

これらのミドルウェアは、サーバー側のリクエストエラーと関数エラーを取得します。

import {
  sentryGlobalFunctionMiddleware,
  sentryGlobalRequestMiddleware,
} from "@sentry/tanstackstart-react";
import { createStart } from "@tanstack/react-start";

export const startInstance = createStart(() => {
  return {
    requestMiddleware: [sentryGlobalRequestMiddleware],
    functionMiddleware: [sentryGlobalFunctionMiddleware],
  };
});

各配列では、Sentry ミドルウェアを先頭にしてください。

ランタイムの起動パターン

ランタイムの方法を1つ選択してください。

ランタイムパターン	使用する状況	備考
--import フラグ	Node の起動フラグを制御できる場合	本番環境でのモニタリングに推奨
src/server.ts での直接インポート	ホストが起動フラグを制限している場合（サーバーレスホストなど）	計測対象がネイティブの Node API に限定されます

--import の例：

{
  "scripts": {
    "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' vite dev --port 3000",
    "build": "vite build && cp instrument.server.mjs .output/server",
    "start": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs"
  }
}

直接インポートによる代替方法（src/server.ts の先頭）：

import "../instrument.server.mjs";

合意した各機能について

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

機能	参照先	読み込むタイミング
エラーモニタリング	${SKILL_ROOT}/references/error-monitoring.md	常に
トレーシング	${SKILL_ROOT}/references/tracing.md	ルート/API のパフォーマンスを可視化する必要がある場合
セッションリプレイ	${SKILL_ROOT}/references/session-replay.md	ユーザー向けアプリの場合
ログ	${SKILL_ROOT}/references/logging.md	構造化ログと相関が必要な場合
ユーザーフィードバック	${SKILL_ROOT}/references/user-feedback.md	アプリ内でのフィードバック収集が必要な場合
TanStack Start の機能	${SKILL_ROOT}/references/tanstackstart-features.md	サーバーエントリ、Vite プラグイン、ソースマップ、ランタイムの起動

各機能について、Read ${SKILL_ROOT}/references/<feature>.md を実行し、手順どおりに進め、動作を検証してください。

---

設定リファレンス

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

オプション	型	デフォルト	備考
dsn	string	—	必須です。空の場合、SDK は無効になります
dataCollection	object	設定されていない場合は保守的	自動収集されるカテゴリ（userInfo、cookies、httpHeaders、httpBodies、queryParams、genAI）を細かく制御します。省略した場合、SDK は sendDefaultPii（デフォルトは false）にフォールバックします。このオブジェクトを渡すと（{} の場合でも）、未設定のカテゴリは許可するデフォルトに切り替わります。カテゴリごとにオプトアウトしてください。
integrations	Integration[]	SDK のデフォルト	必要に応じて TanStack Router のトレーシング、リプレイ、フィードバックを含めます
enableLogs	boolean	false	Sentry.logger.* API を有効にします
tracesSampleRate	number	—	開発環境では 1.0、本番環境ではそれより低い値
replaysSessionSampleRate	number	—	記録する全セッションの割合
replaysOnErrorSampleRate	number	—	記録するエラー発生セッションの割合
tunnel	string	—	オプションの広告ブロッカー回避用エンドポイント
debug	boolean	false	SDK の診断ログ

TanStack Start 固有の API

API	目的
tanstackRouterBrowserTracingIntegration(router)	ブラウザーのナビゲーションをトレースします
wrapFetchWithSentry(...)	fetch ハンドラーでのサーバーリクエストのトレーシングとエラーの捕捉
sentryGlobalRequestMiddleware	リクエスト単位のサーバーエラーを捕捉します
sentryGlobalFunctionMiddleware	サーバー関数のエラーを捕捉します
sentryTanstackStart({...})	ソースマップとミドルウェアの計測に使用する Vite プラグイン

---

検証

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

Issue のテスト（フロントエンド）

<button
  type="button"
  onClick={() => {
    throw new Error("Sentry Test Error");
  }}
>
  Break the world
</button>

トレーシングのテスト（フロントエンド + API ルート）

<button
  type="button"
  onClick={async () => {
    await Sentry.startSpan({ name: "Example Frontend Span", op: "test" }, async () => {
      const res = await fetch("/api/sentry-example");
      if (!res.ok) {
        throw new Error("Sentry Example Frontend Error");
      }
    });
  }}
>
  Break the world
</button>

ログのテスト

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 で次の内容を確認してください。

• Issue：フロントエンド／サーバーのエラーが表示されます
• トレース：ブラウザーとサーバーのスパンが表示されます
• リプレイ：有効にした場合、セッションリプレイが表示されます
• ログ：enableLogs: true の場合、ログ行が表示されます
• ユーザーフィードバック：フィードバック連携が有効な場合、送信内容が表示されます

フェーズ 4：相互リンク

TanStack Start のセットアップが完了したら、Sentry を使っていない関連バックエンドが存在するか確認します。

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

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 のドキュメントを使用
Node.js バックエンドサービス	sentry-node-sdk

---

トラブルシューティング

問題	解決策
イベントが表示されない	debug: true を設定し、DSN を確認して、クライアントとサーバーの両方の初期化ファイルが実行されていることを確認します
サーバートレースがない	src/server.ts で wrapFetchWithSentry が使用され、ランタイムで instrument.server.mjs が読み込まれていることを確認します
ルートハンドラーのサーバーエラーが記録されない	配列の先頭に sentryGlobalRequestMiddleware と sentryGlobalFunctionMiddleware があることを確認します
ソースマップが解決されない	sentryTanstackStart の設定で SENTRY_AUTH_TOKEN、org、project を確認します
Vite の設定で SENTRY_AUTH_TOKEN が未定義	loadEnv(mode, process.cwd(), "") または .env.sentry-build-plugin を使用します
リプレイが記録されない	integrations に replayIntegration() があり、サンプルレートがゼロ以外であることを確認します
フィードバックウィジェットが表示されない	feedbackIntegration() が設定されていることを確認し、CSS の z-index の競合を確認します
Sentry にログがない	enableLogs: true を設定し、Sentry.logger.* API を使用します
直接インポートする設定でライブラリのスパンが記録されない	可能であれば --import による起動を優先します。直接インポートでサポートされるのはネイティブの Node インストルメンテーションのみです
SSR のレンダリング例外が自動で取得されない	エラーバウンダリやフォールバックハンドラーで Sentry.captureException を使って手動で取得します