performance

React のランタイムパフォーマンスを診断する

再現可能な操作を1つ計測し、ブラウザーの処理を React のレンダーに関連付け、トレースで裏付けられた結論だけを報告します。

操作を定義する

記録を始める前に、以下を行います。

1. 対象 URL を特定します
2. 再現するための操作を正確に書き出します
3. 期待する結果を選びます
4. 認証が必要かどうかを確認します

利用可能な場合は、本番ビルドを使用してください。開発ビルドではフレームワークの処理が追加され、レンダーやスクリプトのタイミングが歪むことがあります。開発ビルドを計測する必要がある場合は、その制約をレポートに明記してください。

トレースを記録する

対話型ターミナルでスキャンを実行します。

npx react-doctor@latest scan http://localhost:3000 --format json

React Doctor は分離された Chrome プロファイルを開きます。紫色の枠線でレンダーされたコンポーネントを確認しながら、予定した操作を実行してください。操作が落ち着いたら Enter キーを押します。記録は5分後に自動的に停止します。

対話型ユーザーは URL を省略し、検出された localhost アプリを選択するか、別の URL を入力できます。エージェントは、実行の自動化で入力待ちが発生しないよう、必ず明示的に URL を指定してください。

認証済みセッションでは、Chrome DevTools Protocol（CDP）を介して接続します。

npx react-doctor@latest scan https://app.example.com \
  --cdp http://127.0.0.1:9222 \
  --format json

Chrome のトレースはブラウザー全体に適用されるため、CDP には専用のデバッグプロファイルを使用してください。サインインし、空白ページ以外のタブをすべて閉じてからスキャンを開始します。React Doctor はトレースの前に、残っている空白タブを閉じます。Cookie の要求、ブラウザープロファイルのコピー、外部管理されているブラウザーの終了は、決して行わないでください。

圧縮された .json.gz トレースには、URL、ソースパス、アプリケーションの挙動が含まれる場合があります。アップロードが明示的に承認されていない限り、ローカルに保管してください。

レポートを読む

以下の順序でレポートを評価します。

1. キャプチャのサポート状況：React の検出、ビルドの種類、React トラック、Long Animation Frame のサポートを確認します
2. ユーザーへの影響：最も遅い操作、合計ブロッキング時間、Largest Contentful Paint（LCP）、Cumulative Layout Shift（CLS）を確認します
3. ブラウザーの処理：長いフレームとスクリプトのホットスポットを調べ、イベント処理、JavaScript、スタイル、レイアウト、ペイントのコストを確認します
4. React の処理：コンポーネントのレンダー回数、合計セルフタイム、最大セルフタイムを確認します
5. キャプチャの制限：すべての警告を確認し、特にドロップされたイベント数に注意します

以下の解釈ルールに従ってください。

• レンダー回数が多いことは証拠であり、欠陥とは限りません。処理時間とユーザーへの影響をあわせて評価します
• 生成されたチャンク名が示すのはブラウザーの処理であり、その処理を所有するソースコンポーネントではありません
• すべてのコンポーネントのレンダーが低コストでも、操作が遅い原因はブラウザー側にある場合があります
• 同じ操作識別子を持つ複数の Event Timing レコードは、1つの操作を表します
• コンポーネントイベントがドロップされると、ホットスポットの合計値は不完全になります
• 紫色のラベルでアクティブなサブツリーを特定し、記録されたタイミングを使って深刻度を判断します

計測値をソースに関連付ける

リポジトリで、計測されたコンポーネントの表示名とイベントハンドラーを検索します。候補ごとに、記録されたフローで実行されることを確認してから報告してください。

サマリーだけでは長いフレームの原因を説明できない場合は、DevTools のトレースを開きます。操作のタイムスタンプを、スクリプトタスク、スタイルまたはレイアウトの処理、React トラック、ペイントと関連付けてください。近接したタイムスタンプだけから因果関係を推測しないでください。

調査結果を報告する

以下の構成を使用します。

## Flow tested

tested_url, build_type, and exact_interaction

## Verdict

one_evidence_backed_paragraph

## Evidence

| Signal            |                  Measurement | Interpretation  |
| ----------------- | ---------------------------: | --------------- |
| Worst interaction |                  duration_ms | measured_cause  |
| Total blocking    |                  duration_ms | measured_scope  |
| Top component     | render_count and duration_ms | measured_impact |

## Findings

1. `path/to/component.tsx:42`: measured_problem, evidence, and smallest_fix

## Limits

capture_warnings, missing_support, or environmental_caveats

静的な lint の指摘でレポートを水増ししないでください。ランタイムの証拠からテスト対象のフローとの関連が確認できる場合に限り、ソースに関する指摘を含めます。

修正を検証する

コード変更が依頼されていない限り、コードを編集しないでください。修正後は、以下を行います。

1. 同じモードで再ビルドします
2. 同じビューポートで同じ操作を記録します
3. タイミングのばらつきによって結論が変わる可能性がある場合は、修正前と修正後にそれぞれ3回ずつサンプルを記録します
4. 操作時間、ブロッキング時間、コンポーネントの処理時間について中央値を比較します
5. 動作とアクセシビリティに悪影響がないことを確認します

記録範囲の外に処理を移すだけの改善や、有用な動作を無効にする改善は採用しないでください。