vite-plugin-chunk-split

0.5.0 verified Mon Apr 27 auth: no javascript

A Vite plugin for fine-grained chunk splitting (v0.5.0, active development). Provides strategies like 'default', 'all-in-one', 'single-vendor', and 'unbundle' (one chunk per file). Supports custom splitting via regex/string patterns for grouping modules. Differentiates from Vite's built-in rollupOptions.output.manualChunks by offering simpler declarative config and pre-built strategies. Requires Vite ^4 or ^5.

Common errors

error Error: The plugin 'vite-plugin-chunk-split' requires vite version ^4 or ^5, but you have vite@3.2.0. ↓

cause Vite version mismatch; plugin requires Vite 4 or 5.

fix

Upgrade Vite to version 4 or 5.

error TypeError: chunkSplitPlugin is not a function ↓

cause Default import instead of named import.

fix

Use const { chunkSplitPlugin } = require('vite-plugin-chunk-split') or import { chunkSplitPlugin } from 'vite-plugin-chunk-split'.

error Property 'customChunk' does not exist on type 'ChunkSplitOptions'. ↓

cause Typo in option name.

fix

Replace 'customChunk' with 'customSplitting' in config.

Warnings

gotcha Options 'customChunk' does not exist; property is 'customSplitting' only. ↓

fix Use 'customSplitting' instead.

gotcha Strategy 'single-vendor' uses 'customChunk' in examples but it is not an option; the plugin only accepts 'strategy' and 'customSplitting'. ↓

fix Define custom chunk logic via 'customSplitting' only.

deprecated No breaking changes known; check GitHub for updates.

gotcha Incorrect import: import default from 'vite-plugin-chunk-split' returns undefined. ↓

fix Use named import: import { chunkSplitPlugin } from 'vite-plugin-chunk-split'.

Install

npm install vite-plugin-chunk-split

yarn add vite-plugin-chunk-split

pnpm add vite-plugin-chunk-split

Imports

chunkSplitPlugin

wrong

import chunkSplitPlugin from 'vite-plugin-chunk-split'

correct

import { chunkSplitPlugin } from 'vite-plugin-chunk-split'

Named export; default import will fail.

ChunkSplitOptions

wrong

import { ChunkSplitOptions } from 'vite-plugin-chunk-split'

correct

import type { ChunkSplitOptions } from 'vite-plugin-chunk-split'

Use type import for TypeScript type definitions.

chunkSplitPlugin (require)

wrong

const chunkSplitPlugin = require('vite-plugin-chunk-split')

correct

const { chunkSplitPlugin } = require('vite-plugin-chunk-split')

Must destructure require; plugin is not default exported.

Quickstart

Configures the plugin with single-vendor strategy groups react/react-dom into one chunk and files matching /src\/utils/ into another.

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

export default {
  plugins: [
    chunkSplitPlugin({
      strategy: 'single-vendor',
      customSplitting: {
        'react-vendor': ['react', 'react-dom'],
        'utils': [/src\/utils/]
      }
    })
  ]
};