feature-flags-nextjs

Next.js 向け PostHog のフィーチャーフラグ

このスキルを使うと、Next.js アプリケーションに PostHog のフィーチャーフラグを追加できます。

参考ファイル

• references/react.md - React のフィーチャーフラグのインストール - ドキュメント
• references/next-js.md - Next.js - ドキュメント
• references/adding-feature-flag-code.md - フィーチャーフラグのコードの追加 - ドキュメント
• references/best-practices.md - フィーチャーフラグのベストプラクティス - ドキュメント

API の詳細やフレームワーク固有のパターンについては、ドキュメントを参照してください。

主な原則

• 環境変数：PostHog のキーには必ず環境変数を使用してください。コードに直接記述しないでください。
• 変更は最小限に：既存のロジックにフィーチャーフラグのコードを追加してください。既存のコードを置き換えたり、構成し直したりしないでください。
• まずはブール型フラグ：ユーザーから多変量フラグを明示的に求められない限り、ブール型フラグのチェックを使用してください。
• 可能な限りサーバーサイドで処理：UI のちらつきを防ぐため、サーバーサイドでのフラグ評価を優先してください。

PostHog MCP ツール

PostHog MCP サーバーが接続されているか確認してください。利用できる場合は、フィーチャーフラグの管理（フラグの作成、一覧表示、更新、削除）に関するツールを探してください。ユーザーにダッシュボードでの手動操作を求めるのではなく、これらのツールを使って PostHog のフラグを直接管理してください。

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

• Next.js 15.3 以降では、最も簡単なセットアップのために instrumentation-client.ts で PostHog を初期化します
• PostHog の React フック（useFeatureFlagEnabled、useFeatureFlagPayload）は、posthog-js がすでに初期化されていれば、PostHogProvider がなくても動作します（例：instrumentation-client.ts を使用する場合）
• クライアントコンポーネントでは、フックを直接インポートして使用します。React コンテキストはデフォルトで posthog-js シングルトンを参照します
• フィーチャーフラグを使うためだけにコンポーネントを PostHogProvider でラップしないでください。posthog-js がグローバルに初期化されていれば不要です
• サーバーコンポーネントとルートハンドラーでは React フックを使用できません。代わりに posthog-node SDK を使用してください
• posthog-node を使ってサーバーサイドの PostHog クライアントを作成し、getAllFlags() または getFeatureFlag() を呼び出してから、posthog.shutdown() を await します
• ハイドレーションの不一致を防ぐため、フラグの値はサーバーからクライアントコンポーネントへ props として渡します
• 初期レンダリングに影響するフラグは、UI のちらつきを防ぐためにサーバーサイドで評価し、props として渡します
• クライアントサイドのフックは、フラグの読み込み中に最初は undefined を返すことがあります。この読み込み状態を処理してください
• フィーチャーフラグには、useFeatureFlagEnabled() または useFeatureFlagPayload() フックを使用してください。これらのフックは読み込み状態と外部同期を自動的に処理します
• ユーザー操作が発生するイベントハンドラーに分析イベントの capture を追加してください。状態変化に反応する useEffect には追加しないでください
• データ変換に useEffect を使用しないでください。派生値はレンダリング時に計算してください
• ユーザーイベントへの応答に useEffect を使用しないでください。そのロジックはイベントハンドラー自体に記述してください
• 状態更新を連鎖させるために useEffect を使用しないでください。関連する更新はすべてイベントハンドラー内でまとめて計算してください
• 親コンポーネントへの通知に useEffect を使用しないでください。イベントハンドラー内で setState と同時に親のコールバックを呼び出してください
• prop の変更時にコンポーネントの状態をリセットするには、useEffect を使用せず、prop をコンポーネントの key として渡してください
• useEffect を使用できるのは、外部システム（React 以外のウィジェット、ブラウザー API、ネットワークのサブスクリプション）との同期に限られます