integration-react-tanstack-router-file-based

TanStack Router（ファイルベース）を使用した React 向け PostHog の統合

このスキルは、TanStack Router（ファイルベース）を使用する React アプリケーションに PostHog アナリティクスを追加するのに役立ちます。

ワークフロー

統合を完了するには、次の手順を順番に実行してください。

1. basic-integration-1.0-begin.md - PostHog のセットアップ - 開始 ← ここから始めてください
2. basic-integration-1.1-edit.md - PostHog のセットアップ - 編集
3. basic-integration-1.2-revise.md - PostHog のセットアップ - 修正
4. basic-integration-1.3-conclude.md - PostHog のセットアップ - 結論

参考ファイル

• references/EXAMPLE.md - TanStack Router（ファイルベース）を使用した React のサンプルプロジェクトコード
• references/tanstack-start.md - TanStack Start - ドキュメント
• references/identify-users.md - ユーザーの識別 - ドキュメント
• references/basic-integration-1.0-begin.md - PostHog のセットアップ - 開始
• references/basic-integration-1.1-edit.md - PostHog のセットアップ - 編集
• references/basic-integration-1.2-revise.md - PostHog のセットアップ - 修正
• references/basic-integration-1.3-conclude.md - PostHog のセットアップ - 結論

サンプルプロジェクトでは、目標とする実装パターンを示しています。API の詳細については、ドキュメントを参照してください。

重要な原則

• 環境変数：PostHog のキーには必ず環境変数を使用してください。ハードコードしないでください。
• 変更は最小限に：既存の統合と並行して PostHog のコードを追加してください。既存のコードを置き換えたり、構成を変更したりしないでください。
• サンプルに合わせる：実装は、可能な限りサンプルプロジェクトのパターンに従ってください。

フレームワークのガイドライン

• フィーチャーフラグには、useFeatureFlagEnabled() または useFeatureFlagPayload() フックを使用してください。これらのフックは、読み込み状態と外部との同期を自動的に処理します。
• ユーザーアクションが発生するイベントハンドラーにアナリティクスのイベント送信処理を追加してください。状態変化に反応する useEffect には追加しないでください。
• データ変換に useEffect を使用しないでください。派生値はレンダリング中に計算してください。
• ユーザーイベントへの対応に useEffect を使用しないでください。そのロジックはイベントハンドラー自体に記述してください。
• 状態更新を連鎖させるために useEffect を使用しないでください。関連する更新はすべてイベントハンドラーでまとめて計算してください。
• 親コンポーネントへの通知に useEffect を使用しないでください。イベントハンドラー内で setState と合わせて親コンポーネントのコールバックを呼び出してください。
• プロパティの変更時にコンポーネントの状態をリセットするには、useEffect を使わず、そのプロパティをコンポーネントの key として渡してください。
• useEffect は、外部システム（React 以外のウィジェット、ブラウザー API、ネットワークのサブスクリプション）との同期にのみ使用してください。
• ページビューのトラッキングには useEffect ではなく、TanStack Router に組み込まれているナビゲーションイベントを使用してください。
• 子ルートから PostHog クライアントにアクセスできるよう、ファイルベースの規約（__root.tsx）またはコードベースの規約（createRootRoute() を呼び出す箇所）で定義されたルートコンポーネントに PostHogProvider を使用してください。

ユーザーの識別

ログインおよびサインアップのイベント時にユーザーを識別してください。このフレームワークに適した識別方法については、サンプルコードとドキュメントを参照してください。フロントエンドとバックエンドの両方のコードがある場合は、相関関係を維持するため、クライアント側のセッション ID と distinct ID を X-POSTHOG-DISTINCT-ID ヘッダーおよび X-POSTHOG-SESSION-ID ヘッダーで渡してください。

エラートラッキング

PostHog のエラートラッキングを関連ファイルに追加してください。特に、重要なユーザーフローや API 境界の周辺に追加してください。