nextjs-bundle-optimizer

Next.js バンドルとビルド時の最適化

Next.js 16 アプリケーション向けの、データに基づく最適化ループです。このスキルでは next experimental-analyze、ビルド、型チェック、テストを連携させ、変更を一度に1つずつ加えて、検証可能な改善を実現します。

適用するタイミング

次のような場合に、このスキルを使用してください。

• Next.js 16 アプリでバンドルサイズ、First Load JS、またはルートバンドルを減らしたい場合。
• 本番ビルドに時間がかかり、ボトルネックを診断して解消したい場合。
• アナライザーの出力やツリーマップのスクリーンショットを共有した場合、または「なぜ <X> はこんなに大きいのか」と質問された場合。
• 新しい依存関係を追加してバンドルが大きくなり、その理由を把握して元に戻したい場合。
• パフォーマンス予算を設定し、段階的に適用したい場合。

なぜ反復するのか（「すべての最適化を一度に適用」しない理由）

バンドルの最適化には、思わぬ問題を引き起こす落とし穴が数多くあります。たとえば、次のようなものです。

• 「クライアント専用」の依存関係を next/dynamic の背後に移すと、初回描画時にその依存関係が存在することを前提としていた SSR の利用側が壊れる場合があります。
• 誤ったパッケージで experimental.optimizePackageImports を使うと、サブパスのエクスポートが誤って解決される場合があります。
• modularizeImports の正規表現を過度に広く設定すると、意図しないモジュールに適用される場合があります。
• ポリフィルの対象を過度に絞り込むと、本番環境で古いモバイルブラウザーが動作しなくなる場合があります。

確実な方法は、**変更を1つ加え、測定し、検証して、コミットする（または元に戻す）**ことだけです。このスキルでは、スクリプトを通じてその手順を徹底します。

前提条件

• Next.js 16 以降のプロジェクト（スキルが package.json から自動検出します）。
• git（このワークフローではチェックポイントにコミットを、ロールバックにリバートを使用します）。
• PATH 上で利用できる jq（analyze／compare スクリプトで使用します）。
• 開始前に作業ツリーがクリーンであること（verify の手順で git status を使って確認します）。
• Next.js 15 以前で webpack モードを使用しているプロジェクトの場合：このスキルがそれを検出し、experimental-analyze の代わりに @next/bundle-analyzer を使用します。gotchas.md を参照してください。

セットアップ

初回使用時に、次を実行します。

bash scripts/baseline.sh --setup

これにより、config.json の設定を対話形式で行います。config.json にすでに値が設定されている場合、スクリプトはそれを使用し、入力を求めません。

ワークフローの概要

┌── 1. baseline ──┐   Clean build, snapshot bundles + timing → baselines/{timestamp}/
│                 │
│   2. analyze ───┤   Run `next experimental-analyze --output`, extract top offenders
│                 │
│   3. diagnose ──┤   Map each offender to a recipe in references/optimizations.md
│                 │
│   ── apply ─────┤   User (or agent) applies ONE recipe. Skill helps draft the change.
│                 │
│   4. measure ───┤   Re-build, re-analyze, save to iterations/{n}/
│                 │
│   5. compare ───┤   Diff vs baseline; flag regressions; print delta table
│                 │
│   6. verify ────┤   Build + tsc + tests + no overall regression. Hard PASS/FAIL.
│                 │
│   commit OR ────┘   `git commit` (PASS+improvement) or `git revert` (FAIL/no win)
│   revert
│
└── loop back to step 2 with new baseline if you want a fresh measurement point.

エラー処理、ロールバック手順、各スクリプトの出力例を含む詳細なループについては、references/workflow.md を参照してください。

クイックリファレンス

スクリプト（Next.js アプリのルートから実行）

スクリプト	目的	出力
scripts/baseline.sh	基準点を設定する	baselines/{ts}/{bundle,timing,manifest}.json
scripts/analyze.sh	アナライザーを実行し、主な問題箇所を解析する	iterations/{n}/findings.json
scripts/diagnose.sh [findings.json]	問題箇所を最適化レシピに対応付ける	stdout：優先順位付きのレシピ一覧
scripts/measure.sh	変更後に再測定する	iterations/{n}/{bundle,timing}.json
scripts/compare.sh [baseline] [current]	スナップショットを比較する	stdout：差分テーブル。悪化した場合は終了コード1
scripts/verify.sh	完全な検証を実行する	終了コード0＝安全にコミット可能、終了コード1＝元に戻す

最適化レシピ

references/optimizations.md では、アナライザーのシグナル別にレシピをまとめています。

バンドルサイズ

• バレルインポートによる肥大化 → experimental.optimizePackageImports（webpack）／Turbopack では自動
• すべてのルートで読み込まれる重いクライアントライブラリ → next/dynamic({ ssr: false })
• クライアントコンポーネントからインポートされているサーバー専用ライブラリ → サーバーコンポーネントに移動
• 依存関係のバージョン重複 → overrides／resolutions で重複を解消
• ポリフィルによる肥大化 → browserslist の対象を絞り込む
• アイコンライブラリでアイコンごとにインポートする

ビルド時間

• experimental.turbopackFileSystemCacheForBuild を有効にする
• transpilePackages の対象を絞り込む（過剰に使うとコンパイル時間が大幅に増加します）
• CI で tsc --noEmit と next build を分離する
• NEXT_TURBOPACK_TRACING=1 で単一ファイルのボトルネックを特定する

各レシピには、シグナル → 修正 → 期待される効果 → 検証手順が記載されています。

注意点

蓄積された失敗しやすいポイントについては、gotchas.md を参照してください。最初は、Next.js 16 でよくある落とし穴を中心にまとめています。

• next build では First Load JS が表示されなくなりました。ビルド出力から grep しないでください。
• optimizePackageImports は Turbopack（16 ではデフォルト）では何もしません。Turbopack が自動的に最適化します。
• ビルド時間を比較する際は、キャッシュの状態を統一する必要があります。.next/ を削除してキャッシュなしの状態にするか、事前にキャッシュを温めてください。

関連スキル

• vercel:nextjs — Next.js App Router 全般のガイダンスです。レシピを適用する際のリファクタリングの判断に参照してください。
• vercel:turbopack — このスキルの範囲を超えるビルド時のデバッグに使用します。
• vercel:next-cache-components — レシピがキャッシュ境界に触れる場合に使用します。