# Madge — Visualize Module Dependencies as Graphs

> Madge generates visual dependency graphs from your JavaScript, TypeScript, or CSS modules, helping you find circular dependencies and understand project structure at a glance.

## Install

Save in your project root:

# Madge — Visualize Module Dependencies as Graphs

## Quick Use
```bash
npm install -g madge
madge --image graph.svg src/index.ts
# Generate a visual dependency graph as SVG
madge --circular src/
# Check for circular dependencies
```

## Introduction
Madge creates dependency graphs from JavaScript, TypeScript, and CSS source files. It parses import and require statements to build a module tree, then renders it as a visual diagram or reports circular dependencies that can cause subtle bugs.

## What Madge Does
- Parses CommonJS, AMD, and ES6 module imports to build a dependency tree
- Detects circular dependencies and reports the exact import chains involved
- Generates visual graphs in SVG, PNG, PDF, or DOT format using Graphviz
- Supports JavaScript, TypeScript, JSX, TSX, and CSS/SASS/LESS files
- Works with webpack and TypeScript path aliases via configuration

## Architecture Overview
Madge uses a combination of detective-based AST parsing (precinct) and the TypeScript compiler API to resolve imports across your project. It builds an adjacency list of module relationships, runs cycle detection via depth-first search, and pipes the graph to Graphviz (dot) for rendering when visual output is requested.

## Self-Hosting & Configuration
- Install globally or as a dev dependency: npm install madge --save-dev
- Install Graphviz separately for image output: brew install graphviz or apt install graphviz
- Configure via .madgerc in your project root or pass a JSON config file
- Map path aliases with webpackConfig or tsConfig options to resolve non-relative imports
- Set fileExtensions to include or exclude specific file types

## Key Features
- Circular dependency detection with full cycle path reporting
- Multiple output formats: JSON tree, text list, DOT graph, or rendered image
- TypeScript and path alias support out of the box with tsconfig resolution
- Exclude patterns to skip node_modules, test files, or generated code
- Programmatic API for integration into build pipelines and CI checks

## Comparison with Similar Tools
- **dependency-cruiser** — More rule-based with policy enforcement; Madge focuses on visualization and circular detection
- **Webpack Bundle Analyzer** — Analyzes bundle size, not module relationships; Madge maps import structure
- **nx graph** — Monorepo-level project dependencies; Madge works at the file/module level within a single project
- **ESLint import/no-cycle** — Lint rule that catches cycles one file at a time; Madge reports all cycles project-wide in one pass

## FAQ
**Q: Does Madge require Graphviz?**
A: Only for image output. JSON, text, and DOT output work without Graphviz. Install Graphviz when you need SVG/PNG rendering.

**Q: Can Madge handle TypeScript path aliases?**
A: Yes. Point Madge to your tsconfig.json with the --ts-config flag and it resolves paths automatically.

**Q: How do I integrate Madge into CI?**
A: Run madge --circular src/ in your CI pipeline. It exits with code 1 when circular dependencies are found, failing the build.

**Q: Does it support monorepos?**
A: Madge works per-directory. Point it at a specific package's source folder and it analyzes that subtree. For cross-package graphs, consider dependency-cruiser.

## Sources
- https://github.com/pahen/madge
- https://www.npmjs.com/package/madge

---
Source: https://tokrepo.com/en/workflows/asset-5578f72d
Author: AI Open Source