babel-plugin-path-chunk-name

1.3.1 verified Sat Apr 25 auth: no javascript

Babel plugin (v1.3.1, last updated 2020) that automatically names dynamic import chunks based on the file path, removing the need for manual webpackChunkName magic comments. It transforms import() to include webpackChunkName derived from the imported module's filename or directory structure. Options include 'delay' mode which wraps import in a function for lazy evaluation. Differentiates from manual comments and NamedChunksPlugin by automating chunk naming with zero configuration, preserving folder structure in output.

Common errors

error Cannot find module 'babel-plugin-path-chunk-name' ↓

cause Plugin not installed or Babel cannot resolve it.

fix

Run npm install babel-plugin-path-chunk-name --save-dev and ensure it's in node_modules.

error ReferenceError: require is not defined ↓

cause Using import statement in .babelrc (ESM) while plugin is CJS.

fix

Use require() or string name in Babel config; avoid ESM imports for config.

error Invalid plugin configuration: must be an array or string ↓

cause Options passed as second argument to string plugin name without array wrapper.

fix

Use nesting array: [["path-chunk-name", { opts }]].

Warnings

breaking Since v1.0, dynamic import paths with variables are converted to '[request]' pattern; chunks may be grouped unexpectedly. ↓

fix Ensure dynamic paths are structured to generate desired chunk names, or use magic comments manually for fine control.

gotcha The 'delay' option wraps import in an arrow function; calling .then() after lazy import will cause the import to be invoked immediately (since v1.2.0). ↓

fix If using .then(), do not enable delay, or wrap import in a function manually to preserve lazy behavior.

gotcha If import is already in a delay wrapper (e.g., () => import('./foo')), the 'delay' option does nothing (since v1.3.0). ↓

fix Remove existing delay wrappers if you want the plugin to handle delay, or ensure consistency.

deprecated Plugin relies on Babel 6/7 API; compatibility with Babel 8 or future versions is not guaranteed. ↓

fix Consider alternative chunk naming strategies if upgrading Babel breaks the plugin.

Install

npm install babel-plugin-path-chunk-name

yarn add babel-plugin-path-chunk-name

pnpm add babel-plugin-path-chunk-name

Imports

default export

wrong

import plugin from 'babel-plugin-path-chunk-name'

correct

module.exports = require('babel-plugin-path-chunk-name')

CJS-only plugin; in Babel config use require() or string name.

Babel config string
wrong
```
plugins: ['babel-plugin-path-chunk-name']
```
correct
```
plugins: ['path-chunk-name']
```
Babel resolves scoped plugins automatically; full name works but not required. Since v1.0.

Options

wrong

plugins: ['path-chunk-name', { delay: true }]

correct

plugins: [['path-chunk-name', { delay: true }]]

Options must be in nested array; wrong placement causes them to be ignored.

Quickstart

Shows basic usage in .babelrc, default path-to-chunk-name transformation, delay mode wrapping, and dynamic import pattern.

// .babelrc
{
  "plugins": ["path-chunk-name"]
}

// Input: import('./components/Header')
// Output: import(/* webpackChunkName: 'Header' */ './components/Header')

// With delay option
{
  "plugins": [["path-chunk-name", { "delay": true }]]
}
// Input: import('./Foo')
// Output: () => import(/* webpackChunkName: 'Foo' */ './Foo')

// Dynamic path with [request] pattern
// Input: import(`./base/${page}`)
// Output: import(/* webpackChunkName: 'base/[request]' */ `./base/${page}`)