rspack-split-chunks
Diagnose and optimize Rspack `optimization.splitChunks` configuration. Use this when a user wants better production chunking, safer `chunks: "all"` defaults, fewer duplicated modules, better long-term caching, `cacheGroups` design help, `maxSize` tuning, or debugging over-fetch caused by `name` and forced chunk merging.
rstackjs · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add rstackjs/agent-skills --skill rspack-split-chunks技能说明
name: rspack-split-chunks
description: >-
Diagnose and optimize Rspack optimization.splitChunks configuration. Use
this when a user wants better production chunking, safer chunks: "all"
defaults, fewer duplicated modules, better long-term caching, cacheGroups
design help, maxSize tuning, or debugging over-fetch caused by name and
forced chunk merging.
Rspack SplitChunks Optimization
Use this skill when the task is to recommend, review, or debug optimization.splitChunks. If you are using ESM library, it's not the same algorithm of this skill.
Default stance
- Distinguish repo defaults from recommended production baselines.
- Rspack's built-in default is
chunks: "async", but for most production web apps the best starting point is:
optimization: {
splitChunks: {
chunks: "all",
},
}
- Keep the default cache groups unless there is a concrete reason to replace them.
- Treat
nameas a graph-shaping option, not a cosmetic naming option. - Do not use
splitChunksto reason about JavaScript execution order or tree shaking. For JS, chunk loading/execution order is preserved by the runtime dependency graph, and tree shaking is decided elsewhere.
Read references/repo-behavior.md when you need the source-backed rationale.
What To Optimize For
First identify which problem the user actually has:
- duplicated modules across entry or async boundaries
- a route fetching a large shared chunk with mostly unused modules
- too many tiny chunks
- a vendor/common chunk that changes too often and hurts caching
- an oversized async or initial chunk that should be subdivided
- confusion about whether
splitChunksaffects runtime execution order
Do not optimize all of these at once. Pick the primary goal and keep the rest as constraints.
Workflow
1. Start from the safest production baseline
Unless the user already has a measured problem that requires custom grouping, prefer:
optimization: {
splitChunks: {
chunks: "all",
},
}
Why:
- it lets splitChunks dedupe modules across both initial and async chunks
- it still only loads chunks reachable from the current entry/runtime
- it usually avoids loading unnecessary modules better than hand-written global vendor buckets
If the existing config disables default or defaultVendors, assume that is suspicious until proven necessary.
2. Audit the config for high-risk knobs
Check these first:
- fixed
name cacheGroups.*.nameenforce: true- disabled
default/defaultVendors - broad
test: /node_modules/rules combined with a single globalname usedExports: false- very small
minSize maxSizecombined with manual global names
3. Interpret name correctly
Use this rule:
- No
name: splitChunks can keep different chunk combinations separate. - Same
name: matching modules are merged into the same named split chunk candidate.
That means a fixed name: "vendors" or name: "common" is often the real reason a page starts fetching modules from unrelated dependency chains.
Prefer these alternatives before adding name:
- keep
nameunset - use
idHintif the goal is filename identity, not grouping identity - narrow the
testso the cache group is smaller - split one broad cache group into several focused cache groups
- rely on
maxSizeto subdivide a big chunk instead of forcing a global name
Use a fixed name only when the user explicitly wants one shared asset across multiple entries/routes and accepts the extra coupling.
4. Preserve the built-in cache groups by default
Rspack's built-in production-oriented behavior depends heavily on these two groups:
default: extracts modules shared by at least 2 chunks and reuses existing chunksdefaultVendors: extractsnode_modulesmodules and reuses existing chunks
These defaults are usually the best balance between dedupe and "only fetch what this page needs".
If you customize cacheGroups, do not casually replace these with one manually named vendor bucket.
5. Use chunks: "all" without fear of breaking execution order
When a module group is split out, Rspack connects the new chunk back to the original chunk groups. That preserves JavaScript loading semantics.
So:
splitChunkschanges chunk topology- the runtime still guarantees dependency loading/execution order
- if execution order appears broken, look for other causes first
- this statement is about JavaScript, not CSS order
6. Use maxSize as a refinement tool
Use maxSize, maxAsyncSize, or maxInitialSize when the problem is "this shared chunk is too large", not when the problem is "I need a stable vendor chunk name".
Important behavior:
maxSizeruns after a chunk already exists- the split is deterministic
- modules are grouped by path-derived keys and split near low-similarity boundaries
- similar file paths tend to stay together
This is usually safer than forcing one giant named vendor chunk, because it keeps chunk graph semantics while subdividing hot spots.
7. Use usedExports deliberately
If the user has multiple runtimes/entries and wants leaner shared chunks per runtime, prefer keeping usedExports enabled.
If they set usedExports: false, expect broader sharing and potentially larger common chunks.
This is still not tree shaking. It only changes how splitChunks groups modules across runtimes.
8. Treat enforce: true as an escape hatch
enforce: true bypasses several normal guardrails. Use it only when the user intentionally wants a split regardless of minSize, minChunks, and request limits.
If a config looks aggressive and hard to explain, check enforce before changing anything else.
Recommendations By Goal
Better default production chunking
Recommend:
optimization: {
splitChunks: {
chunks: "all",
},
}
Avoid:
- disabling
default - disabling
defaultVendors - adding
namebefore me