Fast circular dependency detection for Webpack builds, fully compatible with the original plugin.
npm install fast-circular-dependency-webpack-plugin> 🚀 A high-performance alternative to circular-dependency-plugin.
> Built with Tarjan's Strongly Connected Components (SCC) algorithm for faster and more stable detection of circular dependencies in large-scale projects.
---
The original plugin uses recursive DFS, which can get slow on large projects.
FastCircularDependencyPlugin introduces several improvements:
2. Deterministic module ordering
- Matches the official plugin’s test results by sorting modules by their resource path.
3. Accurate dependency resolution
- Resolves dependencies via compilation.moduleGraph.getModule(dependency) (Webpack 5) or dependency.module (Webpack 4).
- Ignores CommonJsSelfReferenceDependency, missing resources, and async edges when allowAsyncCycles is enabled.
4. Lifecycle hooks supported
- Full support for onStart, onDetected, and onEnd.
- Call signatures and timing are consistent with the original plugin.
5. Robust cycle detection
- Always finds a valid cycle path.
- Includes a minimal fallback mechanism to avoid missing cycles.
---
shell
npm i -D fast-circular-dependency-webpack-plugin
or
pnpm add -D fast-circular-dependency-webpack-plugin
`---
Webpack Compatibility
- âś… Webpack 4.0.1+
- âś… Webpack 5.x
- ⚠️ Webpack 3 is not supported (same as the original v5 release)---
Basic Usage
`js
// webpack.config.js
const FastCircularDependencyPlugin = require('fast-circular-dependency-webpack-plugin')module.exports = {
entry: "./src/index",
plugins: [
new FastCircularDependencyPlugin({
// exclude detection of files based on a RegExp
exclude: /a\.js|node_modules/,
// include only specific files based on a RegExp
include: /dir/,
// add errors to webpack instead of warnings
failOnError: true,
// allow import cycles that include an async import
allowAsyncCycles: false,
// set the current working directory for displaying module paths
cwd: process.cwd(),
})
]
}
`Advanced Usage
Supports the same lifecycle hooks as the original plugin:
`jsx
// webpack.config.js
const FastCircularDependencyPlugin = require('fast-circular-dependency-webpack-plugin')module.exports = {
entry: "./src/index",
plugins: [
new FastCircularDependencyPlugin({
// called before cycle detection starts
onStart({ compilation }) {
console.log('start detecting webpack modules cycles');
},
// called for each detected cycle
onDetected({ module, paths, compilation }) {
//
paths is an array of relative module paths that make up the cycle
compilation.errors.push(new Error(paths.join(' -> ')))
},
// called after cycle detection ends
onEnd({ compilation }) {
console.log('end detecting webpack modules cycles');
},
})
]
}``âś… Drop-in replacement for the original plugin.
âś… Full API compatibility with all existing options and lifecycle hooks.
✅ Much faster on large projects thanks to Tarjan’s algorithm.
This project is a high-performance fork and reimplementation of
circular-dependency-plugin
originally created by Aaron Ackerman and contributors.
Licensed under the ISC License.