mcpField
D
dev-toolbar-review

dev-toolbar-review

github.com/supabaseテスト・品質114.3k187 回インストール今日更新
リポジトリ

dev-toolbar-review について

dev toolbar やその統合箇所を変更するプルリクエスト向けのレビューチェックリストです。環境ガード、機能フラグの上書き、テレメトリー購読、SSE 処理、アプリへのマウントを確認できます。

主な機能

  1. 01local と staging の環境ガードを確認
  2. 02機能フラグ上書き Cookie のレビュー
  3. 03テレメトリーイベント購読の検証
  4. 04SSE ストリームと再接続処理の確認
  5. 05各アプリでの toolbar マウントをレビュー

活用シーン

  1. 01dev toolbar パッケージの変更をレビュー
  2. 02機能フラグ上書き動作を確認
  3. 03テレメトリーや SSE の変更を評価
  4. 04アプリへの toolbar 統合を検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/supabase/supabase --skill dev-toolbar-review

インストール後、Claude Code で/dev-toolbar-reviewを入力して読み込まれたか確認します。

詳細

開発用ツールバーのレビューガイド

開発用ツールバー（packages/dev-tools/）と、packages/common/ の統合箇所に変更を加える PR のレビューチェックリストです。ツールバーはテレメトリーイベントを表示し、ローカル環境とステージング環境でのみフィーチャーフラグをオーバーライドできます。

該当する場合

以下のパスを変更する PR には、growth eng のレビューが必要です。

  • packages/dev-tools/**（CODEOWNERS で @supabase/growth-eng が所有）
  • packages/common/posthog-client.ts（フラグのオーバーライド読み込み、イベントのサブスクリプション）
  • packages/common/feature-flags.tsx（フラグのオーバーライドのマージロジック）
  • アプリレベルのマウント：apps/studio/、apps/www/、apps/docs/ にある DevToolbarProvider／DevToolbar／DevToolbarTrigger

注：posthog-client.ts と feature-flags.tsx は growth-eng の CODEOWNERS に含まれていないため、これらのファイルのみを変更する PR ではレビューが自動でリクエストされません。PR フィードでこれらの変更を確認してください。

レビューチェックリスト

1. 環境ガード

ファイル： packages/dev-tools/index.ts、DevToolbar.tsx、DevToolbarTrigger.tsx、DevToolbarContext.tsx

ツールバーは、次の 2 層の保護を使用します。

  • ビルド時のツリーシェイキング（index.ts）：バンドラーは process.env.NEXT_PUBLIC_ENVIRONMENT をインライン化するため、isToolbarEnabled = env === 'local' || env === 'staging' によってエクスポートの三項演算子が静的になります。これら 2 つの環境以外では、すべてのエクスポートがスタブになります（DevToolbar と DevToolbarTrigger は null をレンダリングし、DevToolbarProvider は子要素をそのまま渡し、useDevToolbar は何もしないコンテキストを返します）。また、実装モジュールはバンドルから除外されます。同じリテラルの process.env チェックが DevToolbarContext.tsx、DevToolbar.tsx、DevToolbarTrigger.tsx、feature-flags.tsx にも重複して記述されています。バンドラーがチェックを直接確認できる必要があるため、これらの内容を一致させてください。
  • 実装内のランタイムガード：IS_LOCAL_DEV = env === 'local' により、ローカル環境限定の部分（DevToolbarContext.tsx の SSE イベントストリームと、DevToolbar.tsx のローカル環境限定 UI）が制限されます。そのため、ステージング環境ではこれらを使わずにツールバーを利用できます。

確認事項：

  • ガードが削除または拡大されていないこと。ツールバーが有効なのは local と staging のみです。プレビュー環境と本番環境のビルドでは、引き続きスタブが使われる必要があります。
  • index.ts のツリーシェイキング用の三項演算子が維持されていること。これらは本番環境での主要な安全策です。
  • 既存のガードパターンを回避する新しいコンポーネントやエクスポートがないこと。
2. フラグのオーバーライド用 Cookie

ファイル： packages/dev-tools/DevToolbar.tsx、packages/common/posthog-client.ts、packages/common/feature-flags.tsx

ツールバーは、ローカルでフィーチャーフラグをオーバーライドする 2 つの Cookie を書き込みます。

  • x-ph-flag-overrides — PostHog のフラグオーバーライド
  • x-cc-flag-overrides — ConfigCat のフラグオーバーライド

これらは、次の箇所で読み取られます。

  • posthog-client.ts:getFeatureFlag() — SDK に問い合わせる前に、PostHog のオーバーライド Cookie を確認します。
  • feature-flags.tsx — 初期化中に両方のオーバーライド Cookie をフラグストアにマージします。

確認事項：

  • Cookie 名が変更されていないこと（書き込み側とすべての読み取り側で一致している必要があります）。
  • feature-flags.tsx のマージ／優先順位ロジックに変更がないこと（現在は vercel-flag-overrides が最初に適用され、ローカル開発では x-cc-flag-overrides が優先されます）。
  • オーバーライド Cookie が IS_LOCAL_DEV／isLocalDev ガードの外で読み取られていないこと。オーバーライドが本番環境のフラグ評価に影響してはなりません。
  • 型強制のバグにつながる可能性がある、packages/dev-tools/utils.ts の parseOverrideValue または valuesAreEqual の変更がないこと。
3. テレメトリーイベントの購読

ファイル： packages/common/posthog-client.ts、packages/dev-tools/DevToolbarContext.tsx

ツールバーは、posthogClient.subscribeToEvents() を介してクライアント側の PostHog イベントを購読します。 PostHog クライアントは、capturePageView、capturePageLeave、 および identify の後に emitToDevListeners() を呼び出します。注：captureExperimentExposure は 開発用リスナーへのイベント送信を行わずに、posthog.capture() を直接呼び出します。そのため、実験の露出イベントはツールバーに表示されません。

確認項目：

  • emitToDevListeners または subscribeToEvents の変更により、実際のイベント送信経路に副作用が生じる可能性（例：エラーの発生、ブロッキング、イベントデータの変更）
  • リスナーセット（devListeners）が同期的に反復され、イベントのディスパッチが遅延する可能性
  • イベントを送信する新しい PostHog クライアントメソッドが emitToDevListeners を呼び出していないこと（ツールバーの表示に漏れが生じます）
4. SSE サーバーテレメトリーストリーム

ファイル： packages/dev-tools/DevToolbarContext.tsx

ツールバーは、Server-Sent Events を介して ${apiUrl}/telemetry/stream に接続し、 サーバー側のテレメトリーを表示します。接続エラー時には指数バックオフを使用します。

確認項目：

  • SSE エンドポイントの URL または session_id Cookie 処理の変更
  • 過剰な再試行や接続リークにつながる可能性がある再接続ロジックの変更
  • 注：ストリームエンドポイントはプラットフォームリポジトリにあります。リポジトリをまたぐ変更には、連携したレビューが必要です
5. アプリへのマウント

プロバイダーとツールバーパネル（DevToolbarProvider、DevToolbar）：

  • apps/studio/pages/_app.tsx
  • apps/www/pages/_app.tsx、apps/www/app/providers.tsx
  • apps/docs/features/app.providers.tsx

トリガーボタン（DevToolbarTrigger）— ナビゲーション／ヘッダーコンポーネント内に個別にレンダリングされます：

  • apps/studio/components/layouts/Navigation/LayoutHeader/LayoutHeader.tsx
  • apps/www/components/Nav/index.tsx
  • apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx

確認項目：

  • プロバイダーがアプリに追加または削除されていること
  • apiUrl プロパティの変更（正しいプラットフォーム API を指している必要があります）
  • ツールバーが PostHog コンテキストにアクセスする際に影響する可能性がある、レンダリング順序の変更

グロースレビューが不要な変更

ツールバーパネル内の UI／UX のみを変更する場合（スタイル、レイアウト、文言、 ドラッグ動作、ポップオーバーの位置など）、上記の統合箇所にも変更が及ばない限り、 グロースエンジニアリングのレビューは不要です。

コメント

Markdown 対応