Repository files navigation

Madge is a developer tool for generating a visual graph of your module dependencies, finding circular dependencies, and giving you other useful info. Joel Kemp's awesomedependency-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
• Will traverse child dependencies automatically

Read thechangelog for latest changes.

I've worked with Madge on my free time for the last couple of years and it's been a great experience. It started as an experiment but turned out to be a very useful tool for many developers. I have many ideas for the project and it would definitely be easier to dedicate more time to it with somefinancial support 🙏

Regardless of your contribution, thanks for your support!

Graph generated from madge's own code and dependencies.

A graph with circular dependencies. Blue has dependencies, green has no dependencies, and red has circular dependencies.

npm -g install madge

Graphviz is only required if you want to generate visual graphs (e.g. in SVG or DOT format).

brew install graphviz|| port install graphviz

apt-get install graphviz

path is a single file or directory, or an array of files/directories to read. A predefined tree can also be passed in as an object.

config is optional and should be theconfiguration to use.

Returns aPromise resolved with the Madge instance object.

Returns anObject with all dependencies.

constmadge=require('madge');madge('path/to/app.js').then((res)=>{console.log(res.obj());});

Returns anObject of warnings.

constmadge=require('madge');madge('path/to/app.js').then((res)=>{console.log(res.warnings());});

Returns anArray of all modules that have circular dependencies.

constmadge=require('madge');madge('path/to/app.js').then((res)=>{console.log(res.circular());});

Returns anObject with only circular dependencies.

constmadge=require('madge');madge('path/to/app.js').then((res)=>{console.log(res.circularGraph());});

Returns anArray of all modules that depend on a given module.

constmadge=require('madge');madge('path/to/app.js').then((res)=>{console.log(res.depends('lib/log.js'));});

Return anArray of all modules that no one is depending on.

constmadge=require('madge');madge('path/to/app.js').then((res)=>{console.log(res.orphans());});

Return anArray of all modules that have no dependencies.

constmadge=require('madge');madge('path/to/app.js').then((res)=>{console.log(res.leaves());});

Returns aPromise resolved with a DOT representation of the module dependency graph. SetcircularOnly to only include circular dependencies.

constmadge=require('madge');madge('path/to/app.js').then((res)=>res.dot()).then((output)=>{console.log(output);});

Write the graph as an image to the given image path. SetcircularOnly to only include circular dependencies. Theimage format to use is determined from the file extension. Returns aPromise resolved with a full path to the written image.

constmadge=require('madge');madge('path/to/app.js').then((res)=>res.image('path/to/image.svg')).then((writtenImagePath)=>{console.log('Image written to '+writtenImagePath);});

Return aPromise resolved with the XML SVG representation of the dependency graph as aBuffer.

constmadge=require('madge');madge('path/to/app.js').then((res)=>res.svg()).then((output)=>{console.log(output.toString());});

You can use configuration file either in.madgerc in your project or home folder or directly inpackage.json. Lookhere for alternative locations for the file.

.madgerc

{"fontSize":"10px","graphVizOptions": {"G": {"rankdir":"LR"    }  }}

package.json

{"name":"foo","version":"0.0.1",..."madge": {"fontSize":"10px","graphVizOptions": {"G": {"rankdir":"LR"      }    }  }}

List dependencies from a single file

madge path/src/app.js

List dependencies from multiple files

madge path/src/foo.js path/src/bar.js

List dependencies from all *.js files found in a directory

madge path/src

List dependencies from multiple directories

madge path/src/foo path/src/bar

List dependencies from all *.js and *.jsx files found in a directory

madge --extensions js,jsx path/src

Finding circular dependencies

madge --circular path/src/app.js

Show modules that depends on a given module

madge --depends wheels.js path/src/app.js

Show modules that no one is depending on

madge --orphans path/src/

Show modules that have no dependencies

madge --leaves path/src/

Excluding modules

madge --exclude'^(foo|bar)\.js$' path/src/app.js

Save graph as a SVG image (requiresGraphviz)

madge --image graph.svg path/src/app.js

Save graph with only circular dependencies

madge --circular --image graph.svg path/src/app.js

Save graph as aDOT file for further processing (requiresGraphviz)

madge --dot path/src/app.js> graph.gv

Using pipe to transform tree (this example will uppercase all paths)

madge --json path/src/app.js| tr'[a-z]''[A-Z]'| madge --stdin

To enable debugging output if you encounter problems, run madge with the--debug option then throw the result in a gist when creating issues on GitHub.

madge --debug path/src/app.js

npm installnpmtest

npm run release

It could happen that the files you're not seeing have been skipped due to errors or that they can't be resolved. Run madge with the--warning option to see skipped files. If you need even more info run with the--debug option.

Madge usesdependency-tree which usesfiling-cabinet to resolve modules. However it requires configurations for each file type (js/jsx) and (ts/tsx). So provide bothwebpackConfig andtsConfig options to madge.

Only one syntax is used by default. You can use both though if you're willing to take the degraded performance. Put this in your madge config to enable mixed imports.

For ES6 + CommonJS:

{"detectiveOptions": {"es6": {"mixedImports":true    }  }}

For TypeScript + CommonJS:

{"detectiveOptions": {"ts": {"mixedImports":true    }  }}

Put this in your madge config.

{"detectiveOptions": {"es6": {"skipTypeImports":true    }  }}

Put this in your madge config.

{"detectiveOptions": {"ts": {"skipTypeImports":true    }  }}

Put this in your madge config.

{"detectiveOptions": {"ts": {"skipAsyncImports":true    },"tsx": {"skipAsyncImports":true    }  }}

Note:tsx is optional, use this when working with JSX.

Ensure you have this in your.tsconfig file.

{"compilerOptions": {"module":"commonjs","allowJs":true  }}

Ensure you haveinstalled Graphviz. If you're running Windows, note that Graphviz is not added to thePATH variable during install. You should add the folder ofgvpr.exe (typically%Graphviz_folder%/bin) to thePATH variable manually.

Homebrew doesn't include GTS by default. Fix this by doing:

brew uninstall graphvizbrew install gtsbrew install graphviz

Try running madge with a different layout, here's a list of the ones you can try:

• dot "hierarchical" or layered drawings of directed graphs. This is the default tool to use if edges have directionality.

• neato "spring model'' layouts. This is the default tool to use if the graph is not too large (about 100 nodes) and you don't know anything else about it. Neato attempts tominimize a global energy function, which is equivalent to statistical multi-dimensional scaling.

• fdp "spring model'' layouts similar to those of neato, but does this by reducing forces rather than working with energy.

• sfdp multiscale version of fdp for the layout of large graphs.

• twopi radial layouts, after Graham Wills 97. Nodes are placed on concentric circles depending their distance from a given root node.

• circo circular layout, after Six and Tollis 99, Kauffman and Wiese 02. This is suitable for certain diagrams of multiple cyclic structures, such as certain telecommunications networks.

This project exists thanks to all the people who contribute.

Thanks to the awesome people below for making donations! 🙏Donate

MIT License