next-bundle-optimizer

バンドルオプティマイザー

1. スコープを設定する

デフォルトでは、すべてのルートと共有クライアント依存関係を対象に、アプリ全体を分析します。ユーザーがルート、依存関係、機能、その他のサブセットを指定した場合にのみ、スコープを絞り込みます。監査モードまたは修正モードを選択します。デフォルトは監査モードです。アプリケーションのソース、依存関係、ロックファイルは変更せずに、アナライザーの成果物を生成し、候補を報告します。修正モードでは、アプリの変更を明示的に依頼する必要があります。表示される動作、タイミング、互換性、または信頼境界を変更する前に、確認してください。ルートの静的な App Shell には、next-cache-components-optimizer を使用します。利用できない場合は、先にインストールしてください（npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-cache-components-optimizer）。ナビゲーションのプリフェッチ作業には、next-partial-prefetching-optimizer を使用します。利用できない場合は、先にインストールしてください（npx skills add https://github.com/vercel/next.js/tree/canary/skills/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' | gzip > /tmp/analyze-app-before.jsonl.gz

--output はビルドを行い、バイナリ／UI の成果物を保存しますが、配信は行いません。next analyze export はビルドせずに保存済みスナップショットを読み込みます。標準出力には行ごとに型付き JSON レコードが出力され、エラーは標準エラー出力に出力されます。アプリ全体を分析する場合は --route を省略し、ユーザー指定のルートを分析する場合は追加します。ルートフィルターを指定しても、アプリ全体のモジュールグラフが維持されるため、次の手順でスコープを絞り込みます。

カスタム 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-app-before.jsonl.gz で解凍し、行指向の分析スクリプトにストリームで渡します。スキーマを使って、対象範囲内のすべてのルートにおけるクライアント／サーバーの寄与を解釈し、指標を選びます。

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

4. 候補を説明する

実際のプロジェクトソースと、正確なインポーターを調べます。アプリ全体、またはユーザーが指定した範囲内で、クライアント出力への寄与を、帰属サイズ、繰り返し頻度、想定されるランタイムコスト、インタラクション前に必要かどうか、正確性のリスクに基づいて順位付けします。

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

複数の機能や大規模な寄与者リストを対象とする広範な監査で改善機会を探る場合は、初期の順位付けの後に、コミュニティ検出 → 対象の選定 → 有向最小カット → ソースの検証を実行します。グラフを構築したりソルバーを実行したりする前に、グラフ手法を読んでください。

1. 検出したコミュニティを、対象範囲内のクライアント出力への帰属寄与で順位付けし、流入するインポーターを調べます。
2. 大規模なコミュニティ、またはその中の任意機能の領域から、インタラクションまで読み込みを遅らせられる可能性のあるものを選びます。ルートのレンダリング条件下で各選択領域が任意である理由を記録します。
3. 検証済みのクライアントルートからそれらの対象への有向最小カットを実行し、対象を切り離せる可能性のある少数のインポーター変更を特定します。
4. カットのエッジをソースと動作上の制約に照らして検証し、調査した各対象を候補、却下したカット、またはエビデンスの不足として記録します。

名前が指定された依存関係や機能を対象とする限定的な監査では、直接のインポーターに基づく推論で関連するパスと提案する境界を十分に説明できる場合、ペアとなるパスを実行しても対象の発見に役立たない理由を記録します。グラフのエビデンスやツール上の制約でこのパスを実行できない場合は、その障害を記録し、それに応じて結論の範囲を限定します。

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

編集を提案する前に、候補ごとに以下の項目を記録します。該当しない項目には理由を記し、証拠が不足している場合は明示的なギャップとして記録します。

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

遅延読み込みされるインタラクション機能、重複パッケージ、サーバーレンダリングされる表示処理、その他の帰属対象アセットについて編集を提案する前に、修正パターンの該当セクションを確認します。

完了条件： 対応するパスと対象の処置が記録されているか、対象を限定してスキップする理由またはブロッカーが明示されていること。すべての候補について、チェックリスト、正確なソース／インポーター、提案する編集、名前付きの動作確認がそろっていること。ヒューリスティクスにはその旨を明記し、証拠のギャップが結論に影響する場合は条件を付けます。レポートの手順をもって audit モードが完了します。

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

小さくまとまりのある変更を1つ加えます。新しい名前で変更後のスナップショットを取得／エクスポートし、ベースラインと同じ分析スコープ、出力クラス、メトリクスを比較します。アプリ全体を分析する場合は、共有依存関係を含むすべてのルートにわたる変更を考慮します。関連する動作テストと型チェックを実行します。実行中のアプリで編集を検証する場合は next-dev-loop を使用し、利用できない場合は先にインストールします（npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop）。

完了条件： スコープ内のメトリクスが改善し、意図した動作が確認に合格した場合に限り、変更を維持します。どちらかの条件を満たさない変更は元に戻します。確認がブロックされている場合は、変更を承認せず、未検証の編集とブロッカーを報告します。次の編集に進む前に、承認した変更後のスナップショットを次のベースラインとして記録します。

6. 報告して終了する

audit のレポートでは候補を報告し、fix のレポートでは承認した編集と、元に戻した試行または未検証の試行を報告します。スナップショット名、スコープ内の帰属／差分、正確なソース／インポーター、動作確認の結果、ブロッカーを含めます。グラフカットについては、ルート／レンダリング条件、ルートと対象、不明点を記載します。ソースの事実、ビルドの証拠、ヒューリスティクス、別途観測した実行時の事実を区別します。

完了条件： スコープ内の候補または試みた編集がすべて、証拠または明示されたギャップとともに説明されていること。