feat: add rspack-split-chunks skill

README.md

@@ -15,6 +15,7 @@ A collection of Agent Skills for [Rstack](https://rspack.rs/guide/start/ecosyste
 
 - [Usage](#usage)
 - [Rspack Skills](#rspack-skills)
+  - [rspack-split-chunks](#rspack-split-chunks)
 - [Rsbuild Skills](#rsbuild-skills)
 - [Rslib Skills](#rslib-skills)
 - [Rspress Skills](#rspress-skills)
@@ -70,6 +71,14 @@ Comprehensive guide and toolkit for diagnosing Rspack build issues. Quickly iden
 
 Use when the user encounters build failures, slow builds, or wants to optimize Rspack performance.
 
+### rspack-split-chunks
+
+```bash
+npx skills add rstackjs/agent-skills --skill rspack-split-chunks
+```
+
+Diagnose and optimize Rspack `optimization.splitChunks` configuration. Use when tuning production chunking, reducing duplicated modules, improving cache behavior, or debugging over-fetch caused by `name` and `cacheGroups`.
+
 ## Rsbuild Skills
 
 ### rsbuild-best-practices

skills/rspack-split-chunks/SKILL.md

@@ -0,0 +1,315 @@
+---
+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:
+
+```js
+optimization: {
+  splitChunks: {
+    chunks: "all",
+  },
+}
+```
+
+- Keep the default cache groups unless there is a concrete reason to replace them.
+- Treat `name` as a graph-shaping option, not a cosmetic naming option.
+- Do not use `splitChunks` to 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`](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 `splitChunks` affects 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:
+
+```js
+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.*.name`
+- `enforce: true`
+- disabled `default` / `defaultVendors`
+- broad `test: /node_modules/` rules combined with a single global `name`
+- `usedExports: false`
+- very small `minSize`
+- `maxSize` combined 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 `name` unset
+- use `idHint` if the goal is filename identity, not grouping identity
+- narrow the `test` so the cache group is smaller
+- split one broad cache group into several focused cache groups
+- rely on `maxSize` to 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 chunks
+- `defaultVendors`: extracts `node_modules` modules 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:
+
+- `splitChunks` changes 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:
+
+- `maxSize` runs 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:
+
+```js
+optimization: {
+  splitChunks: {
+    chunks: "all",
+  },
+}
+```
+
+Avoid:
+
+- disabling `default`
+- disabling `defaultVendors`
+- adding `name` before measuring a real problem
+
+### Avoid fetching non-essential modules
+
+Recommend:
+
+- remove fixed `name`
+- keep cache groups narrow
+- keep `chunks: "all"` if dedupe across initial chunks is still desired
+- inspect which routes now depend on a shared chunk after each change
+
+Avoid:
+
+```js
+cacheGroups: {
+  vendors: {
+    test: /[\\/]node_modules[\\/]/,
+    chunks: "all",
+    name: "vendors",
+    enforce: true
+  }
+}
+```
+
+That pattern often creates one over-shared chunk that many pages must fetch.
+
+### Improve caching without over-merging
+
+Recommend:
+
+- keep `name` unset
+- use `idHint`
+- keep `chunkIds: "deterministic"` or other stable id strategies elsewhere in the config
+- split broad groups into smaller focused groups only when the package boundaries are stable and important
+
+Use a fixed `name` only if the user explicitly prefers cache reuse over route isolation.
+
+### Split a large shared chunk
+
+Recommend:
+
+```js
+optimization: {
+  splitChunks: {
+    chunks: "all",
+    maxSize: 200000,
+  },
+}
+```
+
+Then tune:
+
+- `maxAsyncSize` when async chunks are the pain point
+- `maxInitialSize` when first-load pressure matters more
+- `hidePathInfo` if generated part names should not leak path structure
+
+### Keep an intentionally shared chunk
+
+Recommend a named chunk only when the user says something like:
+
+- "all pages should share one React vendor asset"
+- "I want one framework chunk for cache reuse across routes"
+
+Even then, call out the tradeoff explicitly:
+
+- better cache hit rate
+- more coupling between routes
+- a page may fetch modules it does not execute immediately
+
+## Review Checklist
+
+When reviewing a user's config, explicitly answer:
+
+1. Is the goal dedupe, cache stability, request count, or route isolation?
+2. Is `chunks: "all"` a better baseline than the current config?
+3. Did `name` accidentally turn multiple candidates into one forced shared chunk?
+4. Were `default` or `defaultVendors` disabled without a strong reason?
+5. Would `idHint` satisfy the naming goal without changing grouping?
+6. Is `maxSize` a better fit than a broad manual vendor/common bucket?
+7. Does the result still keep each page fetching only reachable chunks?
+
+## Minimal stats setup
+
+When the task includes diagnosis, ask for or generate stats that expose chunk relations:
+
+```js
+stats: {
+  chunks: true,
+  chunkRelations: true,
+  chunkOrigins: true,
+  entrypoints: true,
+  modules: false
+}
+```
+
+Then compare:
+
+- which entrypoints reference which shared chunks
+- whether a change added a new dependency edge from an entry to a broad shared chunk
+- whether a large shared chunk exists only because of a fixed `name`
+
+## FAQ
+
+### Why do I still see duplicate modules?
+
+Common reasons:
+
+- the shared candidate is too small, so extracting it would not satisfy `minSize`
+- the candidate does not satisfy `minSizeReduction`
+- it does not satisfy `minChunks`
+- request-budget limits reject the split
+- `chunks` / `test` / `cacheGroups` do not actually select the same chunk combination
+
+If the duplicate module is tiny, do not assume this is a bug. Rspack may intentionally keep it in place because splitting it out would create a worse chunk.
+
+### Does splitChunks affect JS execution order?
+
+No.
+
+- `splitChunks` only changes chunk boundaries and dependency edges
+- JS loading and execution order are runtime concerns
+- if a JS ordering bug appears, investigate runtime/bootstrap, side effects, or app code first
+
+### Does splitChunks affect tree shaking?
+
+No.
+
+- tree shaking is controlled by module-graph analysis such as `sideEffects`, `usedExports`, and dead-code elimination
+- `splitChunks` runs later and only reorganizes already-selected modules into chunks
+- `splitChunks.usedExports` is only a grouping hint for runtime-specific chunk combinations; it is not tree shaking itself
+
+### Can splitChunks affect CSS order?
+
+Yes, potentially.
+
+- this caveat applies to CSS order, not JS execution order
+- extracted CSS flows such as `mini-css-extract-plugin` or `experiments.css` can observe changed final CSS order after splitChunks rewrites chunk groups
+- if CSS order is critical, be careful when splitting order-sensitive styles into separate chunks
+
+See [web-infra-dev discussion #12](https://github.com/orgs/web-infra-dev/discussions/12).
+
+## Quick conclusions to reuse
+
+- "Keep `chunks: \"all\"`, keep the default cache groups, and remove `name` unless you intentionally want forced sharing."
+- "`name` is not just a filename hint in Rspack splitChunks; it changes grouping behavior."
+- "`splitChunks` does not control JS execution order or tree shaking; it only changes chunk topology."
+- "`splitChunks` can affect CSS order in extracted-CSS scenarios, so treat CSS as a separate caveat."
+- "`maxSize` is the safer tool when the problem is one chunk being too large."