Skip to content
Detect circular dependencies in modules compiled with Webpack
Branch: master
Clone or download
aackerman Merge pull request #37 from hedgepigdaniel/5.0-async-deps
Add option to allow cycles that include an asynchronous dependency
Latest commit 2ea27ea Apr 27, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
__tests__ Webpack 4 support Mar 2, 2018
.gitignore
.nvmrc Add nvmrc for travis Aug 22, 2017
.travis.yml Remove version from travis.yml file Aug 22, 2017
CHANGELOG.md Update changelog Mar 22, 2018
LICENSE
README.md Set allowAsyncCycles to false by default Apr 27, 2018
index.js Set allowAsyncCycles to false by default Apr 27, 2018
package-lock.json Update version to 5.0.2 for release Apr 13, 2018
package.json Update version to 5.0.2 for release Apr 13, 2018

README.md

Circular Dependency Plugin

Detect modules with circular dependencies when bundling with webpack.

Circular dependencies are often a necessity in complex software, the presence of a circular dependency doesn't always imply a bug, but in the case where you believe a bug exists, this module may help find it.

Webpack Versions

The latest major version of this plugin 5, supports webpack 4.0.1 and greater as a peer dependency. Major version 4 of this plugin and below are intended to support webpack 3.x.x and below as a peer dependency.

Basic Usage

// webpack.config.js
const CircularDependencyPlugin = require('circular-dependency-plugin')

module.exports = {
  entry: "./src/index",
  plugins: [
    new CircularDependencyPlugin({
      // exclude detection of files based on a RegExp
      exclude: /a\.js|node_modules/,
      // add errors to webpack instead of warnings
      failOnError: true,
      // allow import cycles that include an asyncronous import,
      // e.g. via import(/* webpackMode: "weak" */ './file.js')
      allowAsyncCycles: false,
      // set the current working directory for displaying module paths
      cwd: process.cwd(),
    })
  ]
}

Advanced Usage

// webpack.config.js
const CircularDependencyPlugin = require('circular-dependency-plugin')

module.exports = {
  entry: "./src/index",
  plugins: [
    new CircularDependencyPlugin({
      // `onStart` is called before the cycle detection starts
      onStart({ compilation }) {
        console.log('start detecting webpack modules cycles');
      },
      // `onDetected` is called for each module that is cyclical
      onDetected({ module: webpackModuleRecord, paths, compilation }) {
        // `paths` will be an Array of the relative module paths that make up the cycle
        // `module` will be the module record generated by webpack that caused the cycle
        compilation.errors.push(new Error(paths.join(' -> ')))
      },
      // `onEnd` is called before the cycle detection ends
      onEnd({ compilation }) {
        console.log('end detecting webpack modules cycles');
      },
    })
  ]
}

If you have some number of cycles and want to fail if any new ones are introduced, you can use the life cycle methods to count and fail when the count is exceeded. (Note if you care about detecting a cycle being replaced by another, this won't catch that.)

// webpack.config.js
const CircularDependencyPlugin = require('circular-dependency-plugin')

const MAX_CYCLES = 5;
let numCyclesDetected = 0;

module.exports = {
  entry: "./src/index",
  plugins: [
    new CircularDependencyPlugin({
      onStart({ compilation }) {
        numCyclesDetected = 0;
      },
      onDetected({ module: webpackModuleRecord, paths, compilation }) {
        numCyclesDetected++;
        compilation.warnings.push(new Error(paths.join(' -> ')))
      },
      onEnd({ compilation }) {
        if (numCyclesDetected > MAX_CYCLES) {
          compilation.errors.push(new Error(
            `Detected ${numCyclesDetected} cycles which exceeds configured limit of ${MAX_CYCLES}`
          ));
        }
      },
    })
  ]
}
You can’t perform that action at this time.