Madgeis 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-treeis 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 thechangelogfor 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 madgeGraphvizis only required if you want to generate visual graphs (e.g. in SVG or DOT format).
brew install graphviz||port install graphvizapt-get install graphviz
pathis a single file or directory, or an array of files/directories to read. A predefined tree can also be passed in as an object.
configis optional and should be theconfigurationto use.
Returns a
Promiseresolved with the Madge instance object.
Returns an
Objectwith all dependencies.
constmadge=require('madge');
madge('path/to/app.js').then((res)=>{
console.log(res.obj());
});Returns an
Objectof warnings.
constmadge=require('madge');
madge('path/to/app.js').then((res)=>{
console.log(res.warnings());
});Returns an
Arrayof all modules that have circular dependencies.
constmadge=require('madge');
madge('path/to/app.js').then((res)=>{
console.log(res.circular());
});Returns an
Objectwith only circular dependencies.
constmadge=require('madge');
madge('path/to/app.js').then((res)=>{
console.log(res.circularGraph());
});Returns an
Arrayof 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 an
Arrayof all modules that no one is depending on.
constmadge=require('madge');
madge('path/to/app.js').then((res)=>{
console.log(res.orphans());
});Return an
Arrayof all modules that have no dependencies.
constmadge=require('madge');
madge('path/to/app.js').then((res)=>{
console.log(res.leaves());
});Returns a
Promiseresolved with a DOT representation of the module dependency graph. SetcircularOnlyto 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. Set
circularOnlyto only include circular dependencies. Theimage formatto use is determined from the file extension. Returns aPromiseresolved 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 a
Promiseresolved 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());
});| Property | Type | Default | Description |
|---|---|---|---|
baseDir |
String | null | Base directory to use instead of the default |
includeNpm |
Boolean | false | If shallow NPM modules should be included |
fileExtensions |
Array | ['js'] | Valid file extensions used to find files in directories |
excludeRegExp |
Array | false | An array of RegExp for excluding modules |
requireConfig |
String | null | RequireJS config for resolving aliased modules |
webpackConfig |
String | null | Webpack config for resolving aliased modules |
tsConfig |
String|Object | null | TypeScript config for resolving aliased modules - Either a path to a tsconfig file or an object containing the config |
layout |
String | dot | Layout to use in the graph |
rankdir |
String | LR | Sets thedirectionof the graph layout |
fontName |
String | Arial | Font name to use in the graph |
fontSize |
String | 14px | Font size to use in the graph |
backgroundColor |
String | #000000 | Background color for the graph |
nodeShape |
String | box | A string specifying theshapeof a node in the graph |
nodeStyle |
String | rounded | A string specifying thestyleof a node in the graph |
nodeColor |
String | #c6c5fe | Default node color to use in the graph |
noDependencyColor |
String | #cfffac | Color to use for nodes with no dependencies |
cyclicNodeColor |
String | #ff6c60 | Color to use for circular dependencies |
edgeColor |
String | #757575 | Edge color to use in the graph |
graphVizOptions |
Object | false | Custom Graphvizoptions |
graphVizPath |
String | null | Custom Graphviz path |
detectiveOptions |
Object | false | Customdetectiveoptions fordependency-treeandprecinct |
dependencyFilter |
Function | false | Function called with a dependency filepath (exclude subtrees by returning false) |
You can use configuration file either in.madgercin your project or home folder or directly inpackage.json.Lookherefor 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.jsList dependencies from multiple files
madge path/src/foo.js path/src/bar.jsList dependencies from all *.js files found in a directory
madge path/srcList dependencies from multiple directories
madge path/src/foo path/src/barList dependencies from all *.js and *.jsx files found in a directory
madge --extensions js,jsx path/srcFinding circular dependencies
madge --circular path/src/app.jsShow modules that depends on a given module
madge --depends wheels.js path/src/app.jsShow 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.jsSave graph as a SVG image (requiresGraphviz)
madge --image graph.svg path/src/app.jsSave graph with only circular dependencies
madge --circular --image graph.svg path/src/app.jsSave graph as aDOTfile for further processing (requiresGraphviz)
madge --dot path/src/app.js>graph.gvUsing pipe to transform tree (this example will uppercase all paths)
madge --json path/src/app.js|tr'[a-z]''[A-Z]'|madge --stdinTo enable debugging output if you encounter problems, run madge with the
--debugoption then throw the result in a gist when creating issues on GitHub.
madge --debug path/src/app.jsnpm install
npmtestnpm run releaseIt 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--warningoption to see skipped files. If you need even more info run with the--debugoption.
Madge usesdependency-treewhich usesfiling-cabinetto resolve modules. However it requires configurations for each file type (js/jsx) and (ts/tsx). So provide bothwebpackConfigandtsConfigoptions 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:tsxis optional, use this when working with JSX.
Ensure you have this in your.tsconfigfile.
{
"compilerOptions":{
"module":"commonjs",
"allowJs":true
}
}Ensure you haveinstalled Graphviz.If you're running Windows, note that Graphviz is not added to thePATHvariable during install. You should add the folder ofgvpr.exe(typically%Graphviz_folder%/bin) to thePATHvariable manually.
Homebrew doesn't include GTS by default. Fix this by doing:
brew uninstall graphviz
brew install gts
brew install graphvizTry 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 to minimize 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.
-
sfdpmultiscale version of fdp for the layout of large graphs.
-
twopiradial layouts, after Graham Wills 97. Nodes are placed on concentric circles depending their distance from a given root node.
-
circocircular 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
