Registry /
devops / circular-dependency-plugin
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CircularDependencyPlugin
✓ const CircularDependencyPlugin = require('circular-dependency-plugin')
✗ import CircularDependencyPlugin from 'circular-dependency-plugin'
This plugin is designed for webpack config files which typically use CommonJS. ESM import may work but is not officially supported.
CircularDependencyPlugin
✓ new CircularDependencyPlugin({...})
✗ CircularDependencyPlugin({...})
Must be instantiated with `new` as it is a class constructor.
Plugin Options
✓ { exclude: /node_modules/, failOnError: true }
✗ { exclude: 'node_modules', failOnError: 'true' }
Both exclude/include accept RegExp, not strings. failOnError expects boolean, not string.
Webpack configuration integrating CircularDependencyPlugin to detect and warn on circular imports.
// webpack.config.js
const path = require('path');
const CircularDependencyPlugin = require('circular-dependency-plugin');
module.exports = {
entry: './src/index.js',
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'bundle.js'
},
plugins: [
new CircularDependencyPlugin({
exclude: /node_modules/,
include: /dir/,
failOnError: false,
allowAsyncCycles: false,
cwd: process.cwd(),
onDetected({ module: webpackModuleRecord, paths, compilation }) {
compilation.warnings.push(new Error(paths.join(' -> ')));
}
})
]
};
Errors
Common errors & fixes
TypeError: CircularDependencyPlugin is not a constructor
Importing as default export instead of the correct import pattern.
fixUse `const CircularDependencyPlugin = require('circular-dependency-plugin');` with `new`. Circular dependency detected: src/a.js -> src/b.js -> src/a.js
Actual circular import in your codebase.
fixRefactor code to break the cycle or add the cycle to an exclusion list.
Plugin circular-dependency-plugin is not compatible with webpack 3. Please upgrade to webpack 4 or higher.
Using version 5 of the plugin with webpack 3.
fixDowngrade to circular-dependency-plugin@4 or upgrade webpack to >=4.0.1.
Audit
Dependencies
webpackrequiredPeer dependency required to hook into webpack's compilation process