In Vite 8, how do you move an app's `node_modules` code into separate named chunks, and what happened to object-form `manualChunks`?
answer
- the bundler's own options key
- output option, not a plugin
- groups with a name and a test
- priority breaks ties, minSize in bytes
- object form gone, function form deprecated
basics
~20 sVite 8 configures chunk groups in build.rolldownOptions.output.codeSplitting: each group has a name and, usually, a test that captures matching module ids. Object-form manualChunks was removed, the function form is deprecated, and build.rollupOptions is only a deprecated alias.
solid answer
~40 sIn Vite 8 the bundler is Rolldown, so chunking lives at `build.rolldownOptions.output.codeSplitting`. You give it `groups`, each with a `name` (the chunk name, or a function of the module id) and a `test` (a string matched against any id that contains it, a regex or a function). `priority` (default `0`) decides which group wins a module two groups match, and `minSize` (bytes, default `0`) drops a group whose captured modules are too small, letting them fall back to automatic chunking. Groups complement automatic splitting rather than replacing it. Object-form `manualChunks` is no longer supported, the function form is deprecated, and if both `manualChunks` and `codeSplitting` are set, `manualChunks` is ignored. `build.rollupOptions` still works but is a deprecated alias of `build.rolldownOptions`.
code
typescript · 25 linesimport { defineConfig } from 'vite'
export default defineConfig({
build: {
rolldownOptions: {
output: {
codeSplitting: {
groups: [
{
name: 'pdf-viewer',
test: /node_modules[\\/]claims-pdf-viewer/,
priority: 2,
},
{
name: 'vendor',
test: /node_modules/,
priority: 1,
minSize: 20000,
},
],
},
},
},
},
})go deeper
Remember the path build.rolldownOptions.output.codeSplitting and that each group needs a name and usually a test; know that object-form manualChunks is gone in Vite 8.
Explain how test matches module ids, how priority and minSize decide what each group captures, and that groups sit on top of automatic splitting rather than replacing it.
Read the resulting dist: explain the runtime chunk, why a group holds modules its test missed, and why every entry touching a group loads its whole chunk.
Own the migration of shared configs from manualChunks to groups, and decide which chunk layout the platform sets as a default and which apps may override it.
## Where chunking is configured in Vite 8 Vite 8 builds with **Rolldown**. Anything Vite does not expose as its own option is passed to Rolldown through **`build.rolldownOptions`**, which is merged with Vite's internal settings. Chunk shaping is a Rolldown output option, so the full path is `build.rolldownOptions.output.codeSplitting`. `build.rollupOptions` is still accepted, but only as a deprecated alias of `build.rolldownOptions`. `codeSplitting` takes three kinds of value: - `true`, the default: **automatic code splitting**, an entry chunk plus chunks for dynamic imports and shared code. - `false`: inline every dynamic import into a single bundle. - an object with `groups` (and global fallbacks such as `minSize`): **manual code splitting** layered on top of the automatic kind. ## What changed from Vite 7 | Vite 7 form | Status in Vite 8 | Write instead | |---|---|---| | `output.manualChunks` as an object `{ vendor: [...] }` | removed | a group with `name: 'vendor'` and a `test` | | `output.manualChunks` as a function | deprecated; converted to a group whose `name` is that function | a group with a `name` function, or plain groups | | `build.rollupOptions` | deprecated alias | `build.rolldownOptions` | | `manualChunks` and `codeSplitting` both set | `manualChunks` is ignored | keep only `codeSplitting` | ## How a group captures modules - **`name`**: the chunk name, used for `[name]` in the chunk file name. A function receives the module id and returns a name or `null` (skip this module); each distinct returned name becomes its own group. - **`test`**: a **string** captures every module whose id *contains* it; a **regex** is matched against the id; a **function** returns `true` to capture; no `test` matches everything. Rolldown recommends `[\\/]` rather than `/` in path regexes so they also work on Windows. - **`priority`**: default `0`. Higher priority groups claim modules first; on a tie the group declared earlier wins. Once a group becomes a chunk, its modules are removed from the other groups. - **`minSize`**: default `0`, in **bytes**. If the captured modules add up to less, the group is dropped and they fall back to automatic chunking. - **`maxSize`**: a target, not a hard limit; a group above it is split into several chunks near that size. - **`includeDependenciesRecursively`**: default `true`, so a captured module pulls its own dependencies into the group, which reduces the chance of circular chunks. ### Settings that apply to every group `codeSplitting` also accepts global fallbacks, such as `minSize`, `maxSize`, `minShareCount` and `includeDependenciesRecursively`, which a group uses when it does not set its own value. `minShareCount` (default `1`) captures a module only when at least that many entry chunks reference it. When `name` is a function, constraints like `minSize` are applied separately to each name it returns. ## A worked example For a claims portal that keeps a heavy document viewer apart from the rest of its dependencies: 1. A group named `pdf-viewer` with `test: /node_modules[\\/]claims-pdf-viewer/` and `priority: 2` claims the viewer package first. 2. A group named `vendor` with `test: /node_modules/`, `priority: 1` and `minSize: 20000` takes every other dependency, as long as they total at least 20,000 bytes. 3. Application code matches no group, so automatic splitting still gives each lazy route its own chunk. ## What you will notice in `dist` - **A runtime chunk.** When groups are used, Rolldown always emits a separate runtime chunk so its helper code runs before any other chunk, because moving modules between chunks can create circular imports. - **Modules your `test` did not match.** With `includeDependenciesRecursively` left on, a group also holds its captured modules' dependencies. Turning it off is possible, but Rolldown then advises `preserveEntrySignatures: false` or `'allow-extension'` and `strictExecutionOrder: true` to avoid invalid output. - **Whole-chunk loading.** By default a group is one chunk, and every entry that uses any module in it loads all of it. Rolldown's `entriesAware: true` splits a group by which entries import each module. - **The size warning.** `build.chunkSizeWarningLimit` (500 kB uncompressed) still reports any group chunk that grows too large; it does not split anything for you. ## Checking the result 1. Run `vite build` and read the file list it prints: each group appears as `assets/<name>-<hash>.js`, beside the runtime chunk. 2. If a group is missing, check `minSize`: a group below it is dropped silently and its modules return to automatic chunks. 3. Open the network panel on the first page: a group that mixes start-up libraries with a lazy route's library loads that library up front too, because the whole chunk is fetched. Which groups an app should have, such as one vendor chunk or one per library, is a caching and loading-strategy decision. This option is only how Vite 8 carries out whatever you decide.
- A module matches both the `pdf-viewer` and the `vendor` group. Which chunk does it land in?The group with the higher `priority` claims it first, so with `priority: 2` against `1` it lands in `pdf-viewer`. With equal priorities the group declared earlier in the `groups` array wins. Once a group is turned into a chunk, its modules are removed from every other group, so a module is never in two group chunks.
- After adding groups, `dist` contains a chunk you never named, holding only runtime helpers. Where does it come from?Rolldown always generates a separate runtime chunk when manual groups are used. Moving modules between chunks can create circular imports between them, and a shared runtime chunk guarantees the helper code is evaluated before any chunk that needs it. It is expected output, not a misconfiguration.
- Your `vendor` group's chunk also contains a small app module that does not live in `node_modules`. Why?`includeDependenciesRecursively` defaults to `true`, so when a group captures a module it also captures that module's dependencies regardless of `test`, to avoid changing entry chunks' export signatures and to reduce circular chunks. Turning it off is allowed, but Rolldown then recommends `preserveEntrySignatures` set to `false` or `'allow-extension'` and `strictExecutionOrder: true`.
- Object-form manualChunks still works in Vite 8
- build.rollupOptions is the main option name in Vite 8
- A string test must equal the whole module id
- minSize is measured in kilobytes
- Chunk groups switch automatic code splitting off
- Setting manualChunks beside codeSplitting merges the two
Assumes Vite 8: production chunking moved to Rolldown's output.codeSplitting under build.rolldownOptions, object-form manualChunks was removed and its function form deprecated.