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.
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);
});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 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 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.
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.
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!
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 madge
Graphviz is only required if you want to generate visual graphs (e.g. in SVG or DOT format).
brew install graphviz || port install graphviz
apt-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 the configuration to use.
Returns a
Promiseresolved with the Madge instance object.
Returns an
Objectwith all dependencies.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.obj());
});
Returns an
Objectof warnings.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.warnings());
});
Returns an
Arrayof all modules that have circular dependencies.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.circular());
});
Returns an
Objectwith only circular dependencies.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.circularGraph());
});
Returns an
Arrayof 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'));
});
Return an
Arrayof all modules that no one is depending on.
const madge = require('madge');
madge('path/to/app.js').then((res) => {
console.log(res.orphans());
});
Return an
Arrayof all modules that have no dependencies.
const madge = 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.
const madge = 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. The image format to use is determined from the file extension. Returns aPromiseresolved 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);
});
Return a
Promiseresolved 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());
});
| 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"
}
}
}
}
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
To 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.js
npm install
npm test
npm run release
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.
Madge uses dependency-tree which uses filing-cabinet to resolve modules. However it requires configurations for each file type (js/jsx) and (ts/tsx). So provide both webpackConfig and tsConfig options 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
}
}
}
import type statements in ES6 + Flow?Put this in your madge config.
{
"detectiveOptions": {
"es6": {
"skipTypeImports": true
}
}
}
import in type annotations in TypeScript?Put this in your madge config.
{
"detectiveOptions": {
"ts": {
"skipTypeImports": true
}
}
}
Put this in your madge config.
{
"detectiveOptions": {
"ts": {
"skipAsyncImports": true
},
"tsx": {
"skipAsyncImports": true
}
}
}
Note: tsx is optional, use this when working with JSX.
Ensure you have this in your .tsconfig file.
{
"compilerOptions": {
"module": "commonjs",
"allowJs": true
}
}
Ensure you have installed Graphviz. If you're running Windows, note that Graphviz is not added to the PATH variable during install. You should add the folder of gvpr.exe (typically %Graphviz_folder%/bin) to the PATH variable manually.
Homebrew doesn't include GTS by default. Fix this by doing:
brew uninstall graphviz
brew install gts
brew install graphviz
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.
This project exists thanks to all the people who contribute.
Thanks to the awesome people below for making donations! 🙏Donate
MIT License
#391#424#421#422#419#418#4170163dc43a52faee25fa64FAQs
Create graphs from module dependencies.
The npm package madge receives a total of 431,098 weekly downloads. As such, madge popularity was classified as popular.
We found that madge demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.
Security News
A developer is accusing Tencent of violating the GPL by modifying a Python utility and changing its license to BSD, highlighting the importance of copyleft compliance.
Security News
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.