0
# Madge
1

2
Madge is a developer tool for generating visual graphs of your module dependencies, finding circular dependencies, and giving you other useful info. It works for JavaScript (AMD, CommonJS, and ES6 modules) and CSS preprocessors (Sass, Stylus, and Less).
3

4
## Package Information
5

6
- **Package Name**: madge
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install -g madge` (CLI) or `npm install madge` (API)
10

11
## Core Imports
12

13
```javascript
14
const madge = require('madge');
15
```
16

17
For ES6 modules:
18

19
```javascript
20
import madge from 'madge';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const madge = require('madge');
27

28
// Analyze a single file
29
madge('src/app.js').then((res) => {
30
  console.log(res.obj()); // Get dependency tree
31
  console.log(res.circular()); // Find circular dependencies
32
});
33

34
// Analyze a directory
35
madge('src/').then((res) => {
36
  // Generate visual graph
37
  res.image('graph.svg').then((writtenImagePath) => {
38
    console.log('Image written to ' + writtenImagePath);
39
  });
40
});
41
```
42

43
## Architecture
44

45
Madge is built around several key components:
46

47
- **Dependency Analysis**: Core engine that analyzes module dependencies using dependency-tree
48
- **Circular Detection**: Specialized algorithm for finding circular dependencies
49
- **Graph Generation**: Graphviz integration for creating visual dependency graphs
50
- **CLI Interface**: Full command-line tool with extensive options
51
- **Configuration System**: Support for .madgerc and package.json configuration
52

53
## Capabilities
54

55
### Programmatic API
56

57
Core programmatic interface for dependency analysis and graph generation. Perfect for integrating into build tools, CI pipelines, and custom workflows.
58

59
```javascript { .api }
60
function madge(path: string | string[] | object, config?: MadgeConfig): Promise<MadgeInstance>;
61

62
interface MadgeInstance {
63
  obj(): object;
64
  warnings(): object;
65
  circular(): string[];
66
  circularGraph(): object;
67
  depends(id: string): string[];
68
  orphans(): string[];
69
  leaves(): string[];
70
  dot(circularOnly?: boolean): Promise<string>;
71
  image(imagePath: string, circularOnly?: boolean): Promise<string>;
72
  svg(): Promise<Buffer>;
73
}
74
```
75

76
[Programmatic API](./api.md)
77

78
### Command Line Interface
79

80
Full-featured CLI for dependency analysis from the command line. Includes options for output formatting, filtering, and visualization.
81

82
```bash { .api }
83
madge [options] <src...>
84

85
# Key options:
86
-c, --circular          # Show circular dependencies
87
-i, --image <file>      # Write graph to file as an image
88
-j, --json             # Output as JSON
89
--orphans              # Show modules that no one is depending on
90
--leaves               # Show modules that have no dependencies
91
```
92

93
[Command Line Interface](./cli.md)
94

95
## Types
96

97
```javascript { .api }
98
interface MadgeConfig {
99
  baseDir?: string;
100
  excludeRegExp?: string[] | false;
101
  fileExtensions?: string[];
102
  includeNpm?: boolean;
103
  requireConfig?: string;
104
  webpackConfig?: string;
105
  tsConfig?: string | object;
106
  rankdir?: string;
107
  layout?: string;
108
  fontName?: string;
109
  fontSize?: string;
110
  backgroundColor?: string;
111
  nodeColor?: string;
112
  nodeShape?: string;
113
  nodeStyle?: string;
114
  noDependencyColor?: string;
115
  cyclicNodeColor?: string;
116
  edgeColor?: string;
117
  graphVizOptions?: object | false;
118
  graphVizPath?: string | false;
119
  detectiveOptions?: DetectiveOptions | false;
120
  dependencyFilter?: Function | false;
121
}
122

123
interface DetectiveOptions {
124
  es6?: {
125
    mixedImports?: boolean;
126
    skipTypeImports?: boolean;
127
  };
128
  ts?: {
129
    mixedImports?: boolean;
130
    skipTypeImports?: boolean;
131
    skipAsyncImports?: boolean;
132
  };
133
  tsx?: {
134
    skipAsyncImports?: boolean;
135
  };
136
}
137
```