Skip to main content
skill CX Codex

rspack-split-chunks — Claude Code skill: diagnose splitChunks config

rspack-split-chunks teaches the agent to diagnose and tune optimization.splitChunks in Rspack: find duplicate modules, over-fetching, cache group issues, and oversized chunks.

MIT 187 installs ★ 100 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add rstackjs/agent-skills --skill rspack-split-chunks -a claude-code
Open on GitHub

What rspack-split-chunks does

The skill explains how splitChunks parameters affect the chunk graph and helps the agent spot risky patterns. It checks for fixed name values that force routes to fetch unrelated modules and distinguishes repo defaults from production baselines. For most cases, it recommends chunks: "all" without extra groups.

Inside: instructions for analyzing duplicate modules, tuning cache groups, and splitting large chunks with maxSize. The agent references references/repo-behavior.md when it needs source-backed rationale. The skill does not handle tree shaking or JavaScript execution order — those are decided elsewhere in the config.

What it helps with

  • find duplicate modules across entry and async boundaries
  • remove unused modules from shared chunks
  • configure cache groups for stable caching
  • split an oversized vendor chunk
  • verify that chunks: "all" preserves loading order

Example prompts for the agent

  • Why does this route fetch modules from other routes?
  • How do I split vendors.js into smaller chunks without names?
  • Review my splitChunks config — what's risky here?

How to install rspack-split-chunks

1Skills CLI (Vercel)

npx skills add rstackjs/agent-skills --skill rspack-split-chunks -a claude-code

2Manually: put the files in place

~/.claude/skills/rspack-split-chunks/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rspack-split-chunks/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about rspack-split-chunks

How do I install rspack-split-chunks in Claude Code?

Run npx skills add rstackjs/agent-skills --skill rspack-split-chunks -a claude-code, the skill will be installed to ~/.claude/skills/rspack-split-chunks/SKILL.md.

What does the rspack-split-chunks skill do?

It teaches the agent to diagnose optimization.splitChunks in Rspack: find duplicate modules, check cache groups, split large chunks, and explain how parameters affect the chunk graph.

Why does the skill recommend chunks: "all"?

It lets splitChunks deduplicate modules across initial and async chunks while still loading only the chunks reachable from the current entry. This is usually safer than global vendor buckets with a fixed name.

Source text

SKILL.md · MIT
---
name: rspack-split-chunks
description: Diagnose or tune Rspack splitChunks for duplicate modules, route over-fetching, cache groups, caching, or oversized chunks.
---

# 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."

© rstackjs · MIT · rstackjs/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set21

The whole set →
migrate-to-rsbuild migrate-to-rsbuild — a skill that migrates webpack, Vite, Create React App, and Vue CLI projects to Rsbuild. It rewrites build configs and validates dev servers before cleaning up old packages. CX Codex +1 342installs rspack-tracing rspack-tracing — a skill for Claude Code and other IDEs that captures and analyzes Rspack build traces to pinpoint slow compiler phases, plugins, and loaders. Diagnose performance bottlenecks and crashes during development. CX Codex +1 291installs rspack-debugging rspack-debugging captures the crash state of native Rspack with LLDB: backtraces for segfaults, deadlocks and builds that hang. Useful when the failure sits inside Rust. CX Codex +1 282installs storybook-rsbuild The storybook-rsbuild skill sets up Storybook with Rsbuild or migrates an existing project from webpack or Vite. It also handles integrations with Rslib, Modern.js, and Rspack. CX Codex +1 212installs migrate-to-rslib migrate-to-rslib converts TypeScript library builds from tsc or tsup to Rslib with validation before cleanup. CX Codex +1 201installs rspress-v2-upgrade The rspress-v2-upgrade skill automates upgrading an Rspress project from v1 to v2. It reads the config, updates dependencies, rewrites import paths, and validates the build against the official migration guide. CX Codex +1 150installs rstest-debugging rstest-debugging diagnoses Rstest startup, build, runtime, logging, memory, and performance issues with traces and comparable measurements. CX Codex +1 133installs rslib-modern-package The rslib-modern-package skill guides agents through building or reviewing JS/TS libraries with Rslib, from package exports to release readiness. Use it for a new library or a package refresh. CX Codex +1 125installs

Project sponsors

Companies that keep this analytics open