rspack-split-chunks

Rspack SplitChunks の最適化

optimization.splitChunks の推奨、レビュー、デバッグを行う場合に、このスキルを使用してください。ESM ライブラリを使用している場合、このスキルとはアルゴリズムが異なります。

基本方針

• リポジトリのデフォルト設定と、推奨される本番環境の基準を区別します。
• Rspack の組み込みデフォルトは chunks: "async" ですが、ほとんどの本番 Web アプリでは、次の設定を出発点とするのが最適です。

optimization: {
  splitChunks: {
    chunks: "all",
  },
}

• 置き換える具体的な理由がない限り、デフォルトのキャッシュグループを維持してください。
• name は見た目を整える設定ではなく、グラフの構造を変える設定として扱ってください。
• JavaScript の実行順序やツリーシェイキングを検討するために splitChunks を使わないでください。JavaScript のチャンクの読み込み順序と実行順序はランタイムの依存関係グラフによって維持され、ツリーシェイキングは別の仕組みによって決定されます。

根拠となる情報を確認する必要がある場合は、references/repo-behavior.md を読んでください。

最適化の対象

まず、ユーザーが実際に抱えている問題を特定します。

• エントリー間または非同期境界間でモジュールが重複している
• ルートが、ほとんど使われないモジュールを含む大きな共有チャンクを取得している
• 小さなチャンクが多すぎる
• ベンダー／共通チャンクの変更頻度が高く、キャッシュに悪影響を与えている
• 分割すべき大きな非同期チャンクまたは初期チャンクがある
• splitChunks がランタイムの実行順序に影響するかどうか、混乱している

これらすべてを一度に最適化しないでください。主な目標を一つ選び、残りは制約条件として扱います。

ワークフロー

1. 最も安全な本番環境向けの基準から始める

カスタムのグループ化が必要となる、計測済みの問題がすでにない限り、次の設定を優先してください。

optimization: {
  splitChunks: {
    chunks: "all",
  },
}

理由：

• 初期チャンクと非同期チャンクの両方にまたがるモジュールを、splitChunks で重複排除できます
• 現在のエントリー／ランタイムから到達可能なチャンクだけが読み込まれます
• 通常、手書きのグローバルなベンダーバケットよりも、不要なモジュールの読み込みを避けられます

既存の設定で default または defaultVendors が無効になっている場合、必要性が確認されるまでは疑わしいと考えてください。

2. リスクの高い設定項目を確認する

まず、次の項目を確認してください。

• 固定の name
• cacheGroups.*.name
• enforce: true
• 無効化された default／defaultVendors
• name を単一のグローバル名にした、広範な test: /node_modules/ ルール
• usedExports: false
• 非常に小さい minSize
• 手動で指定したグローバル名と組み合わせた maxSize

3. name を正しく理解する

次のルールに従ってください。

• name なし：splitChunks は、異なるチャンクの組み合わせを分けたままにできます。
• 同じ name：一致するモジュールは、同じ名前の分割チャンク候補にまとめられます。

そのため、固定の name: "vendors" や name: "common" は、あるページが無関係な依存関係チェーンのモジュールまで取得し始める主な原因であることが少なくありません。

name を追加する前に、次の方法を優先してください。

• name を未設定のままにする
• グループ化の識別ではなくファイル名の識別が目的なら idHint を使う
• test を絞り込み、キャッシュグループを小さくする
• 広範なキャッシュグループを、目的別の複数のキャッシュグループに分割する
• グローバル名を強制する代わりに maxSize を使って大きなチャンクを細分化する

複数のエントリー／ルート間で一つの共有アセットを使うことをユーザーが明示的に望み、追加の結合を許容する場合にのみ、固定の name を使用してください。

4. 組み込みのキャッシュグループをデフォルトで維持する

Rspack の組み込みの本番環境向け動作は、次の二つのグループに大きく依存しています。

• default：少なくとも 2 つのチャンクで共有されるモジュールを抽出し、既存のチャンクを再利用します
• defaultVendors：node_modules のモジュールを抽出し、既存のチャンクを再利用します

これらのデフォルト設定は通常、重複排除と「このページに必要なものだけを取得すること」のバランスに最も優れています。

cacheGroups をカスタマイズする場合、これらを安易に手動で名前を付けた一つのベンダーバケットに置き換えないでください。

5. 実行順序を壊す心配をせずに chunks: "all" を使用する

モジュールグループが切り出されると、Rspack は新しいチャンクを元のチャンクグループに接続します。これにより、JavaScript の読み込みセマンティクスが維持されます。

つまり：

• splitChunks はチャンクのトポロジーを変更します
• ランタイムは引き続き、依存関係の読み込み／実行順序を保証します
• 実行順序が壊れているように見える場合は、まずほかの原因を確認してください
• この説明は JavaScript に関するものであり、CSS の順序には関係しません

6. maxSize を調整ツールとして使用する

問題が「この共有チャンクが大きすぎる」である場合は、maxSize、maxAsyncSize、または maxInitialSize を使用してください。「安定したベンダーチャンク名が必要」という場合に使用するものではありません。

重要な動作：

• maxSize は、チャンクがすでに存在する場合に適用されます
• 分割は決定的です
• モジュールはパスから導出されたキーでグループ化され、類似度の低い境界付近で分割されます
• 類似したファイルパスは、同じグループにとどまる傾向があります

ホットスポットを細分化しながらチャンクグラフのセマンティクスを保てるため、巨大な名前付きベンダーチャンクを強制するより、通常はこちらのほうが安全です。

7. usedExports を意図的に使用する

複数のランタイム／エントリーがあり、ランタイムごとに共有チャンクをスリム化したい場合は、usedExports を有効にしたままにすることを推奨します。

usedExports: false に設定すると、より広範な共有が行われ、共通チャンクが大きくなる可能性があります。

これは依然としてツリーシェイキングではありません。ランタイムをまたいで splitChunks がモジュールをグループ化する方法を変更するだけです。

8. enforce: true は緊急回避策として扱う

enforce: true は、通常のガードレールをいくつか迂回します。minSize、minChunks、リクエスト数の制限にかかわらず、意図的に分割したい場合にのみ使用してください。

設定が積極的すぎて説明が難しい場合は、ほかの箇所を変更する前に enforce を確認してください。

目標別の推奨事項

本番環境でのチャンク分割の既定値を改善する

推奨：

optimization: {
  splitChunks: {
    chunks: "all",
  },
}

避けること：

• default を無効にする
• defaultVendors を無効にする
• 実際の問題を測定する前に name を追加する

不要なモジュールの取得を避ける

推奨：

• 固定の name を削除する
• キャッシュグループを狭い範囲に保つ
• 初期チャンク間で重複排除したい場合は、chunks: "all" を維持する
• 変更するたびに、どのルートが共有チャンクに依存するようになったかを確認する

避けること：

cacheGroups: {
  vendors: {
    test: /[\\/]node_modules[\\/]/,
    chunks: "all",
    name: "vendors",
    enforce: true
  }
}

このパターンでは、多くのページが取得しなければならない、過度に共有されたチャンクが作られることがよくあります。

結合しすぎずにキャッシュを改善する

推奨：

• name を未設定のままにする
• idHint を使用する
• 設定のほかの箇所では、chunkIds: "deterministic" またはほかの安定した ID 戦略を維持する
• パッケージの境界が安定していて重要な場合にのみ、広範なグループをより小さく目的を絞ったグループに分割する

ルート間の分離よりキャッシュの再利用を明確に優先する場合にのみ、固定の name を使用してください。

大きな共有チャンクを分割する

推奨：

optimization: {
  splitChunks: {
    chunks: "all",
    maxSize: 200000,
  },
}

その後、次のように調整します：

• 非同期チャンクが問題の中心であれば maxAsyncSize
• 初回読み込みの負荷がより重要であれば maxInitialSize
• 生成されるパート名にパス構造を含めたくない場合は hidePathInfo

意図的に共有するチャンクを維持する

ユーザーが次のように述べた場合にのみ、名前付きチャンクを推奨します：

• 「すべてのページで 1 つの React ベンダーアセットを共有したい」
• 「ルート間のキャッシュ再利用のために、1 つのフレームワークチャンクがほしい」

その場合でも、トレードオフを明示してください：

• キャッシュヒット率の向上
• ルート間の結合の増加
• ページが、すぐには実行しないモジュールを取得する可能性

レビューチェックリスト

ユーザーの設定をレビューする際は、次の点に明確に回答してください：

1. 目標は重複排除、キャッシュの安定性、リクエスト数、ルートの分離のどれですか？
2. 現在の設定より chunks: "all" を基本設定とするほうが適切ですか？
3. name によって、複数の候補が意図せず 1 つの強制共有チャンクになっていませんか？
4. 強い理由もなく default または defaultVendors が無効にされていませんか？
5. グループ化を変更せずに idHint で命名の目的を満たせますか？
6. 広範な手動のベンダー／共通バケットより maxSize のほうが適していますか？
7. 各ページが、到達可能なチャンクのみを取得する状態が維持されていますか？

最小限の統計情報の設定

タスクに診断が含まれる場合は、チャンク間の関係を明らかにする統計情報を要求するか、生成してください。

stats: {
  chunks: true,
  chunkRelations: true,
  chunkOrigins: true,
  entrypoints: true,
  modules: false
}

次に、以下を比較します。

• どのエントリーポイントがどの共有チャンクを参照しているか
• 変更によって、エントリーから広範な共有チャンクへの新しい依存関係が追加されたか
• 大きな共有チャンクが固定の name によってのみ存在しているか

FAQ

モジュールがまだ重複して表示されるのはなぜですか？

一般的な理由は次のとおりです。

• 共有候補が小さすぎるため、抽出しても minSize を満たさない
• 候補が minSizeReduction を満たさない
• minChunks を満たさない
• リクエスト数の上限によって分割が拒否される
• chunks ／ test ／ cacheGroups が、実際には同じチャンクの組み合わせを選択していない

重複しているモジュールが小さい場合、これを不具合だと決めつけないでください。分割するとチャンクが悪化するため、Rspack が意図的にそのままにしている可能性があります。

splitChunks は JS の実行順序に影響しますか？

いいえ。

• splitChunks が変更するのは、チャンクの境界と依存関係だけです
• JS の読み込み順序と実行順序はランタイムの問題です
• JS の順序に関する不具合が発生した場合は、まずランタイム／ブートストラップ、副作用、またはアプリのコードを調査してください

splitChunks はツリーシェイキングに影響しますか？

いいえ。

• ツリーシェイキングは、sideEffects、usedExports、デッドコード削除などのモジュールグラフ解析によって制御されます
• splitChunks はその後に実行され、すでに選択されたモジュールをチャンクに再編成するだけです
• splitChunks.usedExports はランタイム固有のチャンクの組み合わせを決めるためのヒントにすぎず、それ自体はツリーシェイキングではありません

splitChunks は CSS の順序に影響することがありますか？

はい、場合によってはあります。

• この注意事項は CSS の順序に関するものであり、JS の実行順序には当てはまりません
• mini-css-extract-plugin や experiments.css などの CSS 抽出処理では、splitChunks によるチャンクグループの書き換え後に、最終的な CSS の順序が変わる場合があります
• CSS の順序が重要な場合は、順序に依存するスタイルを別々のチャンクに分割するときに注意してください

web-infra-dev discussion #12 を参照してください。

再利用できる要点

• 「chunks: \"all\" を維持し、デフォルトのキャッシュグループを維持して、意図的に共有を強制したい場合を除き name を削除してください。」
• 「Rspack の splitChunks における name は、単なるファイル名のヒントではなく、グループ化の動作を変えます。」
• 「splitChunks は JS の実行順序やツリーシェイキングを制御しません。変更するのはチャンクの構造だけです。」
• 「抽出 CSS のケースでは、splitChunks が CSS の順序に影響する場合があるため、CSS は別個の注意事項として扱ってください。」
• 「問題が単一チャンクのサイズが大きすぎることなら、より安全な手段は maxSize です。」