madge

What is madge?

Madge is a JavaScript library that helps you visualize and analyze the dependency graph of your project. It can be used to identify circular dependencies, generate dependency graphs, and more.

What are madge's main functionalities?

Generate Dependency Graph

This feature allows you to generate a dependency graph of your project. The code sample demonstrates how to use Madge to analyze the dependencies in a given project directory and output the result as an object.

const madge = require('madge');

madge('path/to/your/project').then((res) => {
  console.log(res.obj());
});

Identify Circular Dependencies

Madge can identify circular dependencies in your project. The code sample shows how to use Madge to find and log any circular dependencies in the specified project directory.

const madge = require('madge');

madge('path/to/your/project').then((res) => {
  console.log(res.circular());
});

Generate Graphviz DOT File

Madge can generate a Graphviz DOT file for visualizing the dependency graph. The code sample demonstrates how to generate and log the DOT representation of the dependency graph.

const madge = require('madge');

madge('path/to/your/project').then((res) => {
  return res.dot();
}).then((output) => {
  console.log(output);
});

Create an Image of the Dependency Graph

Madge can create an image file of the dependency graph. The code sample shows how to generate an image of the dependency graph and save it as 'graph.png'.

const madge = require('madge');

madge('path/to/your/project').then((res) => {
  return res.image('graph.png');
}).then((writtenImagePath) => {
  console.log('Image written to ' + writtenImagePath);
});

Other packages similar to madge

dependency-cruiser

Dependency-cruiser is a tool to analyze and visualize dependencies in JavaScript and TypeScript projects. It offers similar functionalities to Madge, such as detecting circular dependencies and generating dependency graphs. However, it provides more customization options and supports more file types.

webpack-bundle-analyzer

Webpack-bundle-analyzer is a plugin and CLI utility that represents the size of webpack output files with an interactive zoomable treemap. While it focuses more on bundle size analysis rather than dependency graphs, it provides insights into the structure of your project and helps optimize bundle sizes.

plato

Plato is a JavaScript source code visualization, static analysis, and complexity tool. It generates visual reports of your codebase, including dependency graphs. Compared to Madge, Plato offers a broader range of static analysis features but may not be as focused on dependency graph generation.

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.

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)

Only required if you want to generate the visual graphs using Graphviz.

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());
});

.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);
	});

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
layout	String	dot	Layout to use in the graph
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
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
dependencyFilter	Function	false	Function called with a dependency filepath (exclude substree by returning false)

Note that when running the CLI it's possible to use a runtime configuration file. The config should placed in .madgerc in your project or home folder. Look here for alternative locations for the file. Here's an example:

{
	"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

Excluding modules

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

Save graph as a SVG image (graphviz required)

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

Save graph as a DOT file for further processing (graphviz required)

$ 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 test

FAQ

Missing dependencies?

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.

What's the "Error: write EPIPE" when exporting graph to image?

Ensure you have Graphviz installed. And if you're running Windows graphviz is not setting PATH variable during install. You should add the folder of gvpr.exe (typically %Graphviz_folder%/bin) to PATH variable.

The image produced by madge is very hard to read, what's wrong?

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 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.

• 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.

License

MIT License