Vite 8 manualChunks: Migrate Rollup Splits to Rolldown codeSplitting

Map the old and new configuration boundaries#

An older Vite configuration may look like this:

1
export default defineConfig({
2
  build: {
3
    rollupOptions: {
4
      output: {
5
        manualChunks: {
6
          vendor: ['react', 'react-dom'],
7
        },
8
      },
9
    },
10
  },
11
});

In Vite 8, move the underlying bundler options and express the split as a codeSplitting.groups rule:

1
export default defineConfig({
2
  build: {
3
    rolldownOptions: {
4
      output: {
5
        codeSplitting: {
6
          groups: [
7
            {
8
              test: /node_modules\//,
9
              name: 'vendor',
10
            },
11
          ],
12
        },
13
      },
14
    },
15
  },
16
});

The migration guide also lists build.rollupOptions as deprecated in favor of build.rolldownOptions. Update the outer option at the same time so a later Vite upgrade does not leave the old compatibility name scattered through the config.

Do not blindly split every dependency#

Rolldown’s manual code-splitting documentation warns that moving modules between chunks can change execution behavior. A broad node_modules group is easy to write, but it can create a large vendor chunk, capture dependencies recursively, or alter the order in which modules initialize.

Use a staged migration:

1. Record the old build’s chunk names and the routes that load them.
2. Replace one manualChunks rule with one narrow codeSplitting group.
3. Run the production build and inspect dist/assets.
4. Load the initial route and every route that uses a dynamic import.
5. Check side effects, circular imports, and cache headers before adding another group.

Rolldown may also emit a runtime chunk when manual splitting needs a stable execution order. That is not automatically a regression. The question is whether the resulting application loads and initializes correctly under the deployment’s asset and cache rules.

Check for a silently lost lazy boundary#

A successful build does not prove that a lazy boundary survived. An upstream Vite issue report for Vite 8.2.0 describes the function form of manualChunks being called while its assignments were silently discarded. In that reproduction, a shared CommonJS module returned to a lazy chunk, the entry still imported it statically, and the generated HTML preloaded the supposedly lazy chunk without a warning. The report measured the boot bundle growing from 978 KB to 1,085 KB gzip and all 275 assignments being ignored.

This is a bounded compatibility-path report, not proof that every Vite 8 project has the same failure. Verify the output that your application actually ships:

1
pnpm vite build
2
find dist/assets -maxdepth 1 -type f | sort
3
rg -n 'modulepreload' dist/index.html

Compare the generated entry imports and modulepreload links with the route’s dynamic import. Use this decision table:

Verify the build instead of the config alone#

Run the same build command used by CI, then inspect both the build output and the application behavior:

1
pnpm vite build
2
find dist/assets -maxdepth 1 -type f | sort

For a package script, use pnpm build instead. Check the generated HTML for the expected entry assets and modulepreload links, open a page that loads a lazy chunk, and test a fresh browser profile so a previously cached chunk does not hide a broken import.

If the project still targets an older Vite release, do not copy the Vite 8 configuration into it without checking that release’s supported options. Keep the migration in the same change as the Vite upgrade, or guard the configuration in a way the project can test in both environments.

FAQ#