vite-plugin-chunk-split

Install the plugin as a development dependency using your preferred package manager:

# use npm
npm i vite-plugin-chunk-split -D

# use yarn
yarn add vite-plugin-chunk-split -D

# use pnpm
pnpm i vite-plugin-chunk-split -D

Import chunkSplitPlugin from vite-plugin-chunk-split and add it to the plugins array in your vite.config.ts file.

// vite.config.ts
import { chunkSplitPlugin } from 'vite-plugin-chunk-split';

export default {
  plugins: [
    // ...
    chunkSplitPlugin()
  ]
}

Use the customSplitting option to group specific packages or file patterns into named chunks. The key is the chunk name, and the value is an array of packageInfo (which can be a string for package names or a RegExp for file paths).

Example configurations:

• 'react-vendor': ['react', 'react-dom'] bundles React and React-DOM together.
• 'utils': [/src\/utils/] bundles any file matching the regex into a utils chunk.

// vite.config.ts
import { chunkSplitPlugin } from 'vite-plugin-chunk-split';

export default {
  plugins: [
    chunkSplitPlugin({
      customSplitting: {
        // Bundles react and react-dom together
        'react-vendor': ['react', 'react-dom'],
        // Bundles any file in src/utils using a regex
        'utils': [/src\/utils/]
      }
    })
  ]
}

The strategy option determines the high-level approach to chunking. Available strategies are:

• 'default': The default splitting behavior.
• 'all-in-one': Bundles all files together into a single chunk.
• 'unbundle': Unbundles source files, causing Vite to generate one chunk for every file. This can be used to achieve a bundleless architecture while still allowing specific groups of files to be merged via customSplitting.

To achieve a bundleless setup where Vite generates individual chunks for files, set the strategy to 'unbundle'. You can still use customSplitting to merge specific directories or patterns into shared chunks.

// vite.config.ts
import { chunkSplitPlugin } from 'vite-plugin-chunk-split';

export default {
  plugins: [
    chunkSplitPlugin({
      strategy: 'unbundle',
      customSplitting: {
        // All files in `src/container` will be merged together in the `container` chunk
        'container': [/src\/container/]
      }
    })
  ]
}

To achieve a bundleless (unbundle) setup while still merging specific files into groups, set the strategy to 'unbundle' and use customSplitting to define your groups.

Example: Merging all files under src/container into a single chunk named container while keeping other files separate.

// vite.config.ts
import { chunkSplitPlugin } from 'vite-plugin-chunk-split';

export default {
  plugins: [
    chunkSplitPlugin({
      strategy: 'unbundle',
      customSplitting: {
        // All files under src/container will be merged into one chunk named 'container'
        'container': [/src\/container/]
      }
    })
  ]
}

The configuration interface for the plugin.

type packageInfo = string | RegExp;
type Strategy =
  // Default splitting
  | 'default'
  // All files bundled together
  | 'all-in-one'
  // Bundleless: one file per chunk
  | 'unbundle';

export type CustomSplitting = Record<string, packageInfo[]>;

export interface ChunkSplitOptions {
  strategy?: Strategy;
  customSplitting?: CustomSplitting;
}

The ChunkSplit interface defines the configuration options for the plugin. You can control how chunks are split using a predefined strategy, custom grouping via customSplitting, or fine-grained control with a customChunk function.

import { ChunkSplit } from 'vite-plugin-chunk-split';

const options: ChunkSplit = {
  strategy: 'single-vendor',
  customSplitting: {
    'my-group': ['lodash', /@mui\/.*/],
  },
  useEntryName: true,
};

The customChunk option provides a callback to manually determine the chunk name for any given module. This gives you full control over the output filenames based on the module's context.

const customChunk: (context: {id:string, moduleId:string, file:string, root:string}) => string | undefined | null = (context) => {
  if (context.moduleId.includes('special-module')) {
    return 'special-chunk';
  }
  return undefined;
};

The customSplitting option allows you to group specific packages or modules into named chunks. The value is a record where the key is the chunk name and the value is an array of packageInfo.

packageInfo can be a string (exact package name) or a RegExp (to match module paths).

const customSplitting: Record<string, (string | RegExp)[]> = {
  'react-vendor': ['react', 'react-dom'],
  'ui-library': [/^@mui\//],
};