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 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 have 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. Set circularOnly 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 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 a Buffer.

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 subtrees 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$' path/src/app.js

Save graph as a SVG image (requires Graphviz)

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 a DOT file for further processing (requires Graphviz)

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

Debugging

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

Running tests

npm install
npm test

Creating a release

npm run rele

Madge

Install / Use

README

Examples

See it in action

Installation

Graphviz (optional)

Mac OS X

Ubuntu

API

madge(path: string|array|object, config: object)

Functions

.obj()

.warnings()

.circular()

.circularGraph()

.depends()

.orphans()

.leaves()

.dot([circularOnly: boolean])

.image(imagePath: string, [circularOnly: boolean])

.svg()

Configuration

CLI

Examples

Debugging

Running tests

Creating a release