next-browser-initial-load-optimizer

ブラウザーの初回読み込み最適化

1. スコープを設定する

ルートを選び、監査モードまたは修正モードを選択します。デフォルトは監査モードです。アプリケーションのソース、依存関係、ロックファイルは変更せず、解析用成果物を生成し、候補を報告します。修正モードでは、アプリの変更について明示的な依頼が必要です。表示上の動作、タイミング、互換性、または信頼境界を変更する前に確認してください。ルートの静的な App Shell には next-cache-components-optimizer を、ナビゲーションのプリフェッチ作業には next-partial-prefetching-optimizer を使用します。

**完了条件：**ルート、モード、意図する動作が記録されています。データの取得やエクスポートの依頼は監査モードであり、修正の許可ではありません。

2. ベースラインを取得してエクスポートする

アプリのディレクトリで、そのアプリのパッケージマネージャーを使って実行します。インストール済み CLI の取得オプションは next analyze --help で、再生オプションは next analyze export --help で確認します。選択済みの保存スナップショットを再利用するか、まず識別しやすい名前を付けて取得し、デフォルトの圧縮レベルで gzip 経由でエクスポートします。前後の .jsonl.gz ファイルは分けて保存してください。

**サンドボックス要件：**エージェントのサンドボックスで TCP ポートのバインドがブロックされている場合（Codex の場合など）、next analyze --output による取得はサンドボックスの外で実行しなければなりません。--output は解析 UI を提供しませんが、そのサンドボックス内で取得を試みないでください。

Bash でパイプラインを実行します。

set -o pipefail
# Capture only when a new baseline is needed
pnpm exec next analyze --output --snapshot 'audit-before-unique-1'
pnpm exec next analyze export --snapshot 'audit-before-unique-1' --route '/dashboard' | gzip > /tmp/analyze-dashboard-before.jsonl.gz

--output は、提供を開始せずにバイナリ／UI 成果物をビルドして保存します。next analyze export はビルドせずに保存済みスナップショットを読み込みます。標準出力には、1 行につき 1 つの型付き JSON レコードが出力され、エラーは標準エラー出力に出力されます。ルートフィルターを指定しても、アプリ全体のモジュールグラフは維持されるため、スコープは次のステップで絞り込みます。

カスタムの distDir を使用する場合、--dist-dir <configured-directory>（相対パスまたは絶対パス）を指定して再生します。取得時はアプリの設定を読み込みますが、再生時は読み込みません。--snapshot <name> は保持されている名前を選択し、省略すると最新のスナップショットが選択されます。取得時に名前を省略すると一意なタイムスタンプ名が生成され、明示した名前を再利用すると既存の取得結果が置き換えられます。両方のベースラインを保持できるよう、スペースを含む名前も使い、前後で異なる名前を指定してください。対話的に調査する場合は、--output を指定せずに取得して UI を提供します。next build --analyze でも再生可能なデータが生成されます。

**完了条件：**選択した取得結果が特定され、エクスポートが成功し、ベースラインファイル、スナップショット名、選択したルートが記録されています。圧縮ファイルを処理する前に、パイプライン全体の終了ステータスを確認してください。pipefail を設定すると、gzip がエクスポートの失敗を隠すことを防げます。エクスポートは一度に 1 つのルートを検証するため、gzip -t が成功しても、失敗によって不完全なアーカイブが残る場合があります。エクスポートまたは gzip が失敗した場合は、出力を破棄してください。

3. 証拠を解釈する

アプリにインストールされている Next.jsからスキーマを解決します。その際、Node のランチャーを使用します。

pnpm exec node -p "require.resolve('next/analyze/graph-v1.schema.json')"

レコードの意味、結合、帰属、網羅性に関する説明を読みます。ダンプ全体をコンテキストに読み込むのではなく、gzip -dc /tmp/analyze-dashboard-before.jsonl.gz でストリーム展開し、行単位で処理する分析スクリプトに渡します。スキーマを使って、選択したルートにおけるクライアント／サーバーの寄与を解釈し、指標を選択します。

完了条件：ベースラインのルートに帰属するクライアント／サーバーの寄与と、指標が特定されています。これはビルドの証拠として扱ってください。観測されたブラウザーリクエスト、タイミング、転送量の削減に関する主張には、別途証拠が必要です。

4. 候補を説明する

実際のプロジェクトのソースと、正確なインポーターを調査します。指定されたルートから始めるか、スコープを絞ったクライアント出力の寄与を、帰属サイズ、繰り返しの頻度、実行時コストの見込み、インタラクション前に必要かどうか、正確性に関するリスクで順位付けします。

コミュニティ → 最小カットパス

複数の機能や大規模なコントリビューターリストにまたがる機会を探す広範な監査では、初期ランキングの後に コミュニティ検出 → ターゲット選択 → 有向最小カット → ソース検証 を実行します。グラフを構築したりソルバーを実行したりする前に、グラフ手法 を読んでください。

1. 検出されたコミュニティをスコープ付きクライアント出力の帰属でランク付けし、それらのインバウンドインポーターを調査します。
2. 相互作用を待つことが妥当と考えられる大規模なコミュニティ、またはその中のオプションの機能領域を選択します。選択した各領域が、そのルートのレンダリング条件においてなぜオプションなのかを記録します。
3. 検証済みのクライアントルートからそれらのターゲットへの有向最小カットを実行し、それらを切り離せる可能性のあるインポーター変更の小さな集合を見つけます。
4. カットエッジをソースと動作の制約に対して検証します。調査した各ターゲットを、候補、却下されたカット、または証拠のギャップとして処理します。

名前付きの依存関係や機能の狭い監査では、関連するパスと提案された境界を完全に説明できる場合、直接的なインポーター推論を使用します。ペアのパスが有用なターゲット発見を追加しない理由を記録します。グラフの証拠やツールがパスを妨げる場合は、ブロッカーを記録し、それに応じて結論を限定します。

グラフ証拠チェックリスト

編集を提案する前に、各候補についてこれらの項目を記録します。該当しない項目はその理由を記し、欠落している証拠には明示的なギャップを与えます。

• スコープ: ルート、スナップショット、レンダリング条件、クライアント/サーバー出力クラス、正確なターゲットの識別子とメトリクスを明記します。到達可能性の主張については、該当するクライアント参照を含め、選択したすべてのクライアントルートを特定します。
• カバレッジ: 関連する未サポートの出力と未解決の参照を、利用可能な理由とそれが主張に与える影響とともに要約します。完全性が不確かな場合は、既知のサブグラフに結論のスコープを限定します。
• 帰属: 選択した各出力の寄与を一度だけ数えます。重複レコードの処理を記録し、ソースパスとモジュールの識別子を区別します。ソルバーの重みに使用したマッピングを説明し、不明な重みはギャップとして保持します。
• 到達可能性: 遅延境界については、すべて の同期ルートからターゲットへのパス、代替インポーター、循環を確認します。それには、ターゲット自体がルートである場合も含みます。提案された境界が切断するパスと、到達可能なまま残るパスを記録します。非同期インポートと消去された型のみのインポートをソースに対して検証します。
• ソースチェック: インポートのトリガー、マウント時のプリロード、モジュールの副作用、共有ルートを調査します。非同期インポートが実行される条件を記録します。グラフはインデックス化された到達可能性を確立し、after スナップショットは出力された結果と帰属の変更を検証します。
• 手法: 選択した手法、そのパラメーター、およびそれが候補に適している理由を記録します。

遅延相互作用機能、重複パッケージ、サーバーレンダリングの表示作業、その他の帰属されたアセットについては、編集を提案する前に 修正パターン の該当セクションを読んでください。

完了: ペアのパスとそのターゲットの処理が記録されている、または狭いスコープでのスキップ理由やブロッカーが明示されていること。すべての候補に、記入済みのチェックリスト、正確なソース/インポーター、提案された編集、名前付きの動作チェックがあること。ヒューリスティクスはヒューリスティクスとしてラベル付けし、証拠のギャップの影響を受ける結論には限定を付けます。レポートステップで 監査 モードが完了します。

5. 1 つの変更を検証する — 修正モードのみ

1 つの小さくまとまった変更を行います。新しい名前で after スナップショットを取得/エクスポートし、同じルート、出力クラス、メトリクス をベースラインと比較します。関連する動作テストと型チェックを実行します。実行中のアプリで編集を検証する場合は next-dev-loop を使用します。

完了: スコープ付きメトリクスが改善し、意図した動作がそのチェックに合格した場合にのみ、変更を保持します。どちらかの条件が失敗した変更は元に戻します。チェックがブロックされている場合は、検証されていない編集とブロッカーを報告し、それを受け入れないようにします。受け入れた after スナップショットを、次の編集の前に次のベースラインとして記録します。

6. 報告して終了する

監査レポートには候補を記載します。修正レポートには、受け入れられた編集と、元に戻された試みまたは未検証の試みを記載します。スナップショット名、対象範囲ごとの帰属と差分、正確なソース／インポーター、動作確認の結果、阻害要因を含めてください。グラフのカットについては、そのルート／レンダー条件、ルート、ターゲット、不明点を含めてください。ソースの事実、ビルドの証拠、ヒューリスティクス、個別に観測された実行時の事実を区別してください。

完了: 対象範囲内の候補または試みた編集がすべて、証拠または明示された不足情報とともに説明されています。