Webpack Chunk Rename Plugin

1.0.3 verified Sat Apr 25 auth: no javascript maintenance

A webpack plugin to rename chunks, supporting initial chunks with entry, async chunks, and specific chunk naming. Current stable version is 1.0.3 (last release: unknown, possibly unmaintained). Requires webpack 4.1+ and Node >=6.11.7. Differentiates from similar plugins by offering per-chunk renaming with placeholders like [name], [hash], [chunkhash]. Note: webpack 5 compatibility is not documented; may break.

Common errors

error ChunkRenamePlugin is not a constructor ↓

cause Importing with ES module syntax (import) or using .default when the package exports via module.exports directly.

fix

Use const ChunkRenamePlugin = require('webpack-chunk-rename-plugin');

error Cannot read property 'initialChunksWithEntry' of undefined ↓

cause Calling new ChunkRenamePlugin() without an options object.

fix

Pass an options object: new ChunkRenamePlugin({ initialChunksWithEntry: true })

error TypeError: Cannot destructure property 'async' of 'undefined' or 'null' ↓

cause If 'asyncChunks' option is not a string, or if webpack emits chunks without the expected structure (e.g., webpack 5 changes).

fix

Ensure asyncChunks is a string with valid placeholders; avoid using in webpack 5.

error Error: [object Object] is not a valid chunk name ↓

cause Passing a non-string value (e.g., an object) as a chunk name property in options.

fix

Chunk name properties must be strings containing placeholders like '[name].js'.

Warnings

breaking Plugin is only compatible with webpack 4. Use with webpack 5 may cause build failures or incorrect chunk naming. ↓

fix Consider webpack 5 alternatives such as webpack's built-in chunk naming or community plugins explicitly supporting webpack 5.

breaking Requires Node >=6.11.7. Older Node versions cause runtime errors due to unsupported JS features. ↓

fix Upgrade Node to at least 6.11.7 or use a transpiler/polyfill.

gotcha If no options object is passed to constructor, plugin errors with 'Cannot read property 'initialChunksWithEntry' of undefined'. ↓

fix Always provide an options object: new ChunkRenamePlugin({}) or with proper keys.

gotcha Setting 'initialChunksWithEntry: true' uses output.filename pattern for initial chunks; if output.filename is undefined or not set, chunks may be named 'undefined.js'. ↓

fix Ensure output.filename is defined in webpack config.

gotcha Placeholders like [name] in chunk names refer to the original chunk name (the entry key or split chunk name), not a custom alias. Misuse leads to unexpected filenames. ↓

fix Use the entry point key (e.g., 'main') as the chunk name property for per-chunk renaming.

Install

npm install webpack-chunk-rename-plugin

yarn add webpack-chunk-rename-plugin

pnpm add webpack-chunk-rename-plugin

Imports

ChunkRenamePlugin

wrong

import ChunkRenamePlugin from 'webpack-chunk-rename-plugin';

correct

const ChunkRenamePlugin = require('webpack-chunk-rename-plugin');

Package does not export ES modules; use CommonJS require. No default export for ESM.

ChunkRenamePlugin
```
const ChunkRenamePlugin = require('webpack-chunk-rename-plugin').default;
```
Some similar webpack plugins use .default; this plugin directly exports the constructor, so .default is undefined and will cause 'ChunkRenamePlugin is not a constructor' error if used.
ChunkRenamePlugin
wrong
```
new ChunkRenamePlugin()
```
correct
```
new ChunkRenamePlugin({ initialChunksWithEntry: true })
```
Constructor expects an object; calling with no arguments passes undefined, leading to runtime error when options are accessed. Always pass at least an empty object.

Quickstart

Shows basic usage: rename initial chunks using output.filename, async chunks with a template, and a specific chunk by name.

const ChunkRenamePlugin = require('webpack-chunk-rename-plugin');

module.exports = {
  output: {
    filename: '[name].js',
    chunkFilename: '[name].[chunkhash].js',
  },
  entry: {
    main: './src/index.js',
  },
  plugins: [
    new ChunkRenamePlugin({
      initialChunksWithEntry: true,
      asyncChunks: 'async/[name].[chunkhash].js',
      main: 'custom/[name].js',
    }),
  ],
};