madge

Install Madge globally using npm to use it as a CLI tool.

npm -g install madge

Graphviz is required if you want to generate visual graphs in formats like SVG or DOT.

Mac OS X:

brew install graphviz || port install graphviz

Ubuntu:

apt-get install graphviz

Madge uses dependency-tree and precinct. You can fine-tune how it handles specific syntax via detectiveOptions in your configuration.

Enable mixed ES6 + CommonJS imports:

{
  "detectiveOptions": {
    "es6": { "mixedImports": true }
  }
}

Ignore import type in ES6 + Flow:

{
  "detectiveOptions": {
    "es6": { "skipTypeImports": true }
  }
}

Ignore import in type annotations in TypeScript:

{
  "detectiveOptions": {
    "ts": { "skipTypeImports": true }
  }
}

Ignore dynamic imports in TypeScript:

{
  "detectiveOptions": {
    "ts": { "skipAsyncImports": true },
    "tsx": { "skipAsyncImports": true }
  }
}

If you encounter Error: write EPIPE while attempting to export a graph to an image, it is likely because Graphviz is not installed or not accessible in your system's PATH.

On Windows: Graphviz does not automatically add itself to the PATH variable during installation. You must manually add the folder containing gvpr.exe (typically %Graphviz_folder%/bin) to your system's PATH environment variable.

If you receive the error Graphviz not built with triangulation library when using the sfdp layout on macOS via Homebrew, you must install the gts library explicitly. Run the following commands:

brew uninstall graphviz
brew install gts
brew install graphviz

If you encounter problems or missing dependencies, use the --debug flag to enable detailed output. If files are missing, you can also use the --warning flag to see which files were skipped.

madge --debug path/src/app.js

The madge(path, config) function is the primary entry point for the API.

• path: A single file, a directory, an array of files/directories, or a predefined tree object.
• config: An optional configuration object.

Returns a Promise that resolves to a Madge instance object.

const madge = require('madge');
madge('path/to/app.js').then((res) => {
	// Use the Madge instance methods here
});

If the generated image is difficult to read, try using a different Graphviz layout engine. Available layouts include:

• dot: Hierarchical or layered drawings of directed graphs. Best for directed edges.
• neato: Spring model layouts. Best for graphs with fewer than ~100 nodes where the structure is unknown.
• fdp: Spring model layouts that reduce forces rather than working with energy.
• sfdp: A multiscale version of fdp designed for large graphs.
• twopi: Radial layouts where nodes are placed on concentric circles based on distance from a root node.
• circo: Circular layout, suitable for diagrams of multiple cyclic structures (e.g., telecommunications networks).