{"id":19405,"library":"circular-dependency-plugin","title":"Circular Dependency Plugin","description":"A webpack plugin that detects modules with circular dependencies during the bundling process. Current stable version is 5.2.2, released in 2021, with infrequent updates due to stability. It integrates deeply with webpack's compilation lifecycle, offering hooks like onStart, onDetected, and onEnd for custom handling, and supports excluding/including files via RegExp. Unlike static analysis tools, it works on webpack's resolved module graph. Requires webpack >=4.0.1 as a peer dependency.","status":"active","version":"5.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/aackerman/circular-dependency-plugin","tags":["javascript"],"install":[{"cmd":"npm install circular-dependency-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add circular-dependency-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add circular-dependency-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required to hook into webpack's compilation process","package":"webpack","optional":false}],"imports":[{"note":"This plugin is designed for webpack config files which typically use CommonJS. ESM import may work but is not officially supported.","wrong":"import CircularDependencyPlugin from 'circular-dependency-plugin'","symbol":"CircularDependencyPlugin","correct":"const CircularDependencyPlugin = require('circular-dependency-plugin')"},{"note":"Must be instantiated with `new` as it is a class constructor.","wrong":"CircularDependencyPlugin({...})","symbol":"CircularDependencyPlugin","correct":"new CircularDependencyPlugin({...})"},{"note":"Both exclude/include accept RegExp, not strings. failOnError expects boolean, not string.","wrong":"{ exclude: 'node_modules', failOnError: 'true' }","symbol":"Plugin Options","correct":"{ exclude: /node_modules/, failOnError: true }"}],"quickstart":{"code":"// webpack.config.js\nconst path = require('path');\nconst CircularDependencyPlugin = require('circular-dependency-plugin');\n\nmodule.exports = {\n  entry: './src/index.js',\n  output: {\n    path: path.resolve(__dirname, 'dist'),\n    filename: 'bundle.js'\n  },\n  plugins: [\n    new CircularDependencyPlugin({\n      exclude: /node_modules/,\n      include: /dir/,\n      failOnError: false,\n      allowAsyncCycles: false,\n      cwd: process.cwd(),\n      onDetected({ module: webpackModuleRecord, paths, compilation }) {\n        compilation.warnings.push(new Error(paths.join(' -> ')));\n      }\n    })\n  ]\n};","lang":"javascript","description":"Webpack configuration integrating CircularDependencyPlugin to detect and warn on circular imports."},"warnings":[{"fix":"Set allowAsyncCycles: false to detect cycles involving async imports (default behavior).","message":"Plugin only works on modules that webpack resolves; it does not detect cycles from dynamic imports unless allowAsyncCycles is set to false.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"If using webpack 3.x, use circular-dependency-plugin@4 or lower.","message":"Version 5 dropped support for webpack 3.x and below. Only webpack >=4.0.1 is supported.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Remove the `cwd` option; webpack's internal module resolution handles it.","message":"The `cwd` option is deprecated in favor of using module context directly.","severity":"deprecated","affected_versions":">=5.0.0"},{"fix":"Use `failOnError: false` to emit warnings only (default).","message":"Setting `failOnError: true` will cause webpack to emit errors instead of warnings, potentially breaking the build.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use `const CircularDependencyPlugin = require('circular-dependency-plugin');` with `new`.","cause":"Importing as default export instead of the correct import pattern.","error":"TypeError: CircularDependencyPlugin is not a constructor"},{"fix":"Refactor code to break the cycle or add the cycle to an exclusion list.","cause":"Actual circular import in your codebase.","error":"Circular dependency detected: src/a.js -> src/b.js -> src/a.js"},{"fix":"Downgrade to circular-dependency-plugin@4 or upgrade webpack to >=4.0.1.","cause":"Using version 5 of the plugin with webpack 3.","error":"Plugin circular-dependency-plugin is not compatible with webpack 3. Please upgrade to webpack 4 or higher."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}