Vite Plugin WebpackChunkName

1.0.4-beta.1 verified Mon Apr 27 auth: no javascript

A Vite plugin that enables webpack-style `webpackChunkName` magic comments for code splitting, allowing developers to name dynamic imports in Vite projects. Current stable version 1.0.4-beta.1 supports Vite 5 (v1.x) and Vite 4 or lower (v0.2.x). Key differentiator: provides a familiar webpack syntax for chunk naming on Vite/Rollup, with a simple manualChunksPlugin() API. Not for third-party packages; supports user-defined manual chunks via callback. Actively maintained with TypeScript types included.

Common errors

error TypeError: manualChunksPlugin is not a function ↓

cause Imported as default instead of named export.

fix

Use import { manualChunksPlugin } from 'vite-plugin-webpackchunkname'.

error Error: Dynamic imports with webpackChunkName not working for third-party packages ↓

cause Plugin does not support node_modules.

fix

Use manualChunks rollup option for third-party packages.

error [vite] server configuration error: property 'manualChunks' is not allowed ↓

cause Setting manualChunks in build.rollupOptions.output while plugin is active.

fix

Remove manualChunks from Vite config and use plugin option instead.

Warnings

breaking v1.x supports Vite 5; v0.x supports Vite 4 or lower. Upgrading Vite requires matching plugin major version. ↓

fix Use v1.x for Vite 5, v0.2.x for Vite 4. Check your Vite version before installing.

gotcha Third-party packages are not supported. The plugin only works for your own code dynamic imports. ↓

fix Plugin cannot chunk node_modules packages; use Rollup manualChunks for that.

gotcha Plugin overrides build.rollupOptions.output.manualChunks. Custom manual chunks must be passed via the plugin option, not Rollup config. ↓

fix Pass manualChunks callback to manualChunksPlugin() instead of setting it in Vite config build.rollupOptions.output.manualChunks.

gotcha When using unplugin-vue-components, you must add 'include: [/\\.vue$/, /\\.vue\\?/]' to avoid the plugin breaking dynamic imports. ↓

fix Add the include option to Components() as shown in the README.

Install

npm install vite-plugin-webpackchunkname

yarn add vite-plugin-webpackchunkname

pnpm add vite-plugin-webpackchunkname

Imports

manualChunksPlugin

wrong

import manualChunksPlugin from 'vite-plugin-webpackchunkname'

correct

import { manualChunksPlugin } from 'vite-plugin-webpackchunkname'

Export is named, not default. Must use destructured import.

ManualChunksPluginOptions
```
import type { ManualChunksPluginOptions } from 'vite-plugin-webpackchunkname'
```
TypeScript users can import the options type for strict typing.

vite-plugin-webpackchunkname

wrong

const manualChunksPlugin = require('vite-plugin-webpackchunkname')

correct

const { manualChunksPlugin } = require('vite-plugin-webpackchunkname')

CommonJS require works but must use destructuring for named exports.

Quickstart

Configures the plugin in vite.config.ts with optional custom manual chunks, and demonstrates how to use webpackChunkName magic comments in dynamic imports.

// vite.config.ts
import { defineConfig } from 'vite';
import { manualChunksPlugin } from 'vite-plugin-webpackchunkname';

export default defineConfig({
  plugins: [
    manualChunksPlugin({
      // optional: custom manual chunks override
      manualChunks: (id: string) => {
        if (id.includes('node_modules/lodash/')) return 'lodash';
      }
    })
  ]
});

// In your code, use dynamic imports with webpackChunkName comment:
// import(/* webpackChunkName: "detail" */ '@/detail/somepage.vue')