All Skills > SDK Setup > 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 では通常はい；ルート + フェッチ計装は即座に価値を提供
セッションリプレイ	ユーザー向けアプリ、ログインフロー、チェックアウトフロー、または再現困難な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___",
      sendDefaultPii: true,

      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___",
  sendDefaultPii: true,
  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 でサーバーエントリポイントを計装

フェッチハンドラを 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 プラグイン、ソースマップ、ランタイムスタートアップ

各フィーチャーについて: ${SKILL_ROOT}/references/<feature>.md を読み、手順に従い、動作を確認してください。

---

設定リファレンス

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

オプション	型	デフォルト	注記
dsn	string	—	必須；空の場合 SDK は無効
sendDefaultPii	boolean	false	リクエストヘッダーと IP 由来のユーザーコンテキストを送信
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(...)	サーバーリクエストトレーシング + フェッチハンドラのエラー捕捉
sentryGlobalRequestMiddleware	リクエストレベルのサーバー側エラーを捕捉
sentryGlobalFunctionMiddleware	サーバー関数エラーを捕捉
sentryTanstackStart({...})	ソースマップとミドルウェア計装用の Vite プラグイン

---

検証

テストイベントをトリガーして Sentry がデータを受信することを確認します。

イシューテスト（フロントエンド）

<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 で確認します：

• イシュー: フロントエンド/サーバーエラーが表示されているか
• トレース: ブラウザとサーバースパンが表示されているか
• リプレイ: 有効な場合、セッションリプレイが表示されているか
• ログ: 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 が配列の最初にあることを確認
ソースマップが解決されない	SENTRY_AUTH_TOKEN、sentryTanstackStart 設定の org、project を確認
Vite 設定で SENTRY_AUTH_TOKEN が未定義	loadEnv(mode, process.cwd(), "") または .env.sentry-build-plugin を使用
リプレイが記録されない	replayIntegration() が integrations にあることを確認し、サンプルレートがゼロでないことを確認
フィードバックウィジェットが見えない	feedbackIntegration() が設定されていることを確認し、CSS z-index の競合を確認
Sentry にログがない	enableLogs: true を設定し、Sentry.logger.* API を使用
直接インポートセットアップがライブラリスパンを見落とす	可能な場合は --import スタートアップを優先；直接インポートはネイティブ Node 計装のみに対応
SSR レンダリング例外が自動捕捉されない	エラーバウンダリ/フォールバックハンドラで Sentry.captureException で手動キャプチャ