How to avoid circular dependencies in your JavaScript monorepo

Circular or cyclic dependencies could easily cause bugs in your application. When your modules reference each other you create circular dependency.

Introducing Madge

Madge is a great npm package to check for circular dependencies

Madge is a developer tool for generating a visual graph of your module dependencies, finding circular dependencies, and give you other useful info. Joel Kemp's awesome dependency-tree is used for extracting the dependency tree.

  • Works for JavaScript (AMD, CommonJS, and ES6 modules)
  • Also works for CSS preprocessors (Sass, Stylus, and Less)
  • NPM installed dependencies are excluded by default (can be enabled)
  • All core Node.js modules (assert, path, fs, etc) are excluded
  • ill traverse child dependencies automatically

Global installation

npm -g i madge


yarn global add madge

Check for circular dependencies locally

madge . -c --no-spinner
Screen Shot 2019-06-26 at 12 14 52

Automate circular dependency check with CI pipeline

I would recommend to include circular dependency check as a part of your CI pipeline and make it required so you can be sure that with new changes to the codebase you do not introduce circular dependencies.

Just add the madge command to your package.json:

  "scripts": {
    "find-circular-dependencies": "madge --webpackConfig=./packages/main webpack.config.js --circular --warning --no-spinner src packages"

Include madge in your dev dependencies

npm i --only=dev madge


yarn add -D madge
  "devDependencies": {
    "madge": "3.4.4"

Screen Shot 2019-06-25 at 17 33 56