integration-react-tanstack-router-code-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 を配置してください。

ユーザーの識別

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

エラートラッキング

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