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());
});
.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()
Returns a
Promise
resolved with a DOT representation of the module dependency graph.
const madge = require('madge');
madge('path/to/app.js')
.then((res) => res.dot())
.then((output) => {
console.log(output);
});
.image(imagePath: string)
Write the graph as an image to the given image path. The image format to use is determined from the file extension. Returns a
Promise
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