circular-dependency-plugin

What is circular-dependency-plugin?

The circular-dependency-plugin is an npm package used to detect circular dependencies in JavaScript projects. It is particularly useful in large codebases where circular dependencies can lead to difficult-to-debug issues and performance problems.

What are circular-dependency-plugin's main functionalities?

Basic Usage

This code demonstrates the basic usage of the circular-dependency-plugin in a webpack configuration. It shows how to exclude certain files, include specific directories, fail on error, and set the current working directory.

const CircularDependencyPlugin = require('circular-dependency-plugin');

module.exports = {
  // other webpack config
  plugins: [
    new CircularDependencyPlugin({
      // exclude detection of files based on a RegExp
      exclude: /a\.js|node_modules/,
      // include specific files based on a RegExp
      include: /dir/,
      // add errors to webpack instead of warnings
      failOnError: true,
      // allow import cycles that include an asyncronous import,
      allowAsyncCycles: false,
      // set the current working directory for displaying module paths
      cwd: process.cwd(),
    })
  ]
};

Custom Error Message

This code sample shows how to customize the error message when a circular dependency is detected. The onDetected callback allows you to push a custom error message to the compilation errors.

const CircularDependencyPlugin = require('circular-dependency-plugin');

module.exports = {
  // other webpack config
  plugins: [
    new CircularDependencyPlugin({
      onDetected({ module: webpackModuleRecord, paths, compilation }) {
        compilation.errors.push(new Error(paths.join(' -> ')));
      }
    })
  ]
};

Other packages similar to circular-dependency-plugin

madge

Madge is a JavaScript library that can analyze the dependency graph of your project and detect circular dependencies. Unlike circular-dependency-plugin, which is a webpack plugin, Madge can be used as a standalone tool or integrated into various build processes.

dependency-cruiser

Dependency-cruiser is a tool to analyze and visualize dependencies in JavaScript and TypeScript projects. It can detect circular dependencies and offers more extensive analysis options compared to circular-dependency-plugin. It can be used as a CLI tool or integrated into build processes.

README

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 the you believe a bug exists, this module may help find it.

Basic Usage

// webpack.config.js
let 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
    })
  ]
}

Advanced Usage

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

module.exports = {
  entry: "./src/index",
  plugins: [
    new CircularDependencyPlugin({
      // `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(' -> ')))
      }
    })
  ]
}