README
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
- Will traverse child dependencies automatically
Read the changelog 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 some financial support đ
Regardless of your contribution, thanks for your support!
Examples
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.
See it in action
Installation
npm -g install madge
Graphviz (optional)
Graphviz is only required if you want to generate visual graphs (e.g. in SVG or DOT format).
Mac OS X
brew install graphviz || port install graphviz
Ubuntu
apt-get install graphviz
API
madge(path: string|array|object, config: object)
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 the configuration to use.
Returns a
Promise
resolved with the Madge instance object.
Functions
.obj()
Returns an
Object
with all dependencies.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.obj());
});
.warnings()
Returns an
Object
of warnings.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.warnings());
});
.circular()
Returns an
Array
of all modules that has circular dependencies.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.circular());
});
.circularGraph()
Returns an
Object
with only circular dependencies.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.circularGraph());
});
.depends()
Returns an
Array
of all modules that depend on a given module.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.depends('lib/log.js'));
});
.orphans()
Return an
Array
of all modules that no one is depending on.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.orphans());
});
.leaves()
Return an
Array
of all modules that have no dependencies.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.leaves());
});
.dot([circularOnly: boolean])
Returns a
Promise
resolved with a DOT representation of the module dependency graph. SetcircularOnly
to only include circular dependencies.
const madge = require('madge');
madge('path/to/app.js')
.then((res) => res.dot())
.then((output) => {
console.log(output);
});
.image(imagePath: string, [circularOnly: boolean])
Write the graph as an image to the given image path. Set
circularOnly
to only include circular dependencies. The image format to use is determined from the file extension. Returns aPromise
resolved with a full path to the written image.
const madge = require('madge');
madge('path/to/app.js')
.then((res) => res.image('path/to/image.svg'))
.then((writtenImagePath) => {
console.log('Image written to ' + writtenImagePath);
});
.svg()
Return a
Promise
resolved with the XML SVG representation of the dependency graph as aBuffer
.
const madge = require('madge');
madge('path/to/app.js')
.then((res) => res.svg())
.then((output) => {
console.log(output.toString());
});
Configuration
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 the direction of 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 the shape of a node in the graph |
nodeStyle |
String | rounded | A string specifying the style of 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 Graphviz options |
graphVizPath |
String | null | Custom Graphviz path |
detectiveOptions |
Object | false | Custom detective options for dependency-tree and precinct |
dependencyFilter |
Function | false | Function called with a dependency filepath (exclude substree by returning false) |
You can use configuration file either in .madgerc
in your project or home folder or directly in package.json
. Look here 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"
}
}
}
}
CLI
Examples
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