0
# CLI Tool
1

2
The webpack-bundle-analyzer CLI tool provides standalone bundle analysis capabilities for existing webpack stats files. It offers flexible output modes, server functionality, and comprehensive configuration options for analyzing webpack bundles outside of the build process.
3

4
## Capabilities
5

6
### Command Line Interface
7

8
Analyze webpack bundle stats files using the command line interface.
9

10
```bash { .api }
11
# Command format
12
webpack-bundle-analyzer <bundleStatsFile> [bundleDir] [options]
13

14
# Basic usage
15
webpack-bundle-analyzer stats.json
16

17
# With bundle directory
18
webpack-bundle-analyzer stats.json ./dist
19

20
# With options
21
webpack-bundle-analyzer stats.json ./dist --mode static --port 9999
22
```
23

24
### CLI Arguments
25

26
```javascript { .api }
27
interface CLIArguments {
28
  /** Path to webpack stats JSON file (required) */
29
  bundleStatsFile: string;
30
  /** Directory containing generated bundles (optional, defaults to stats file directory) */
31
  bundleDir?: string;
32
}
33
```
34

35
### CLI Options
36

37
Complete set of command line options for customizing analysis behavior.
38

39
```javascript { .api }
40
interface CLIOptions {
41
  /** Display version number */
42
  '-V, --version'?: boolean;
43
  /** Analysis mode: server, static, or json */
44
  '-m, --mode <mode>'?: 'server' | 'static' | 'json';
45
  /** Host for server mode */
46
  '-h, --host [host]'?: string;
47
  /** Port for server mode */
48
  '-p, --port <n>'?: number | 'auto';
49
  /** Output file path for static/json modes */
50
  '-r, --report <file>'?: string;
51
  /** Report title */
52
  '-t, --title <title>'?: string;
53
  /** Default size type to display */
54
  '-s, --default-sizes <type>'?: 'stat' | 'parsed' | 'gzip';
55
  /** Don't open browser automatically */
56
  '-O, --no-open'?: boolean;
57
  /** Asset exclusion patterns */
58
  '-e, --exclude <regexp>'?: string[];
59
  /** Log level */
60
  '-l, --log-level <level>'?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
61
  /** Display help */
62
  '-h, --help'?: boolean;
63
}
64
```
65

66
**Usage Examples:**
67

68
```bash
69
# Generate webpack stats file
70
webpack --profile --json > stats.json
71

72
# Basic analysis with server mode (default)
73
webpack-bundle-analyzer stats.json
74

75
# Static HTML report
76
webpack-bundle-analyzer stats.json --mode static --report bundle-report.html
77

78
# JSON report
79
webpack-bundle-analyzer stats.json --mode json --report bundle-data.json
80

81
# Custom server configuration
82
webpack-bundle-analyzer stats.json --mode server --host 0.0.0.0 --port 8080
83

84
# With asset exclusions
85
webpack-bundle-analyzer stats.json --exclude vendor --exclude "\.css$"
86

87
# Silent mode with custom title
88
webpack-bundle-analyzer stats.json --log-level silent --title "Production Bundle"
89
```
90

91
### Server Mode
92

93
Start an HTTP server with interactive bundle visualization.
94

95
```bash { .api }
96
# Server mode options
97
webpack-bundle-analyzer stats.json [bundleDir] \
98
  --mode server \
99
  --host <host> \
100
  --port <port> \
101
  --default-sizes <type> \
102
  --title <title> \
103
  --exclude <pattern> \
104
  --log-level <level>
105
```
106

107
**Default Values:**
108
- Host: `127.0.0.1`
109
- Port: `8888`
110
- Default sizes: `parsed`
111
- Auto-open browser: `true`
112

113
**Usage Examples:**
114

115
```bash
116
# Basic server
117
webpack-bundle-analyzer stats.json
118

119
# Custom host and port
120
webpack-bundle-analyzer stats.json --host localhost --port 9999
121

122
# Auto-assign port
123
webpack-bundle-analyzer stats.json --port auto
124

125
# Don't open browser
126
webpack-bundle-analyzer stats.json --no-open
127

128
# Show gzipped sizes by default
129
webpack-bundle-analyzer stats.json --default-sizes gzip
130
```
131

132
### Static Mode
133

134
Generate a single HTML file with embedded bundle visualization.
135

136
```bash { .api }
137
# Static mode options
138
webpack-bundle-analyzer stats.json [bundleDir] \
139
  --mode static \
140
  --report <filename> \
141
  --title <title> \
142
  --default-sizes <type> \
143
  --exclude <pattern> \
144
  --no-open
145
```
146

147
**Default Values:**
148
- Report filename: `report.html`
149
- Auto-open browser: `true`
150

151
**Usage Examples:**
152

153
```bash
154
# Basic static report
155
webpack-bundle-analyzer stats.json --mode static
156

157
# Custom filename
158
webpack-bundle-analyzer stats.json --mode static --report my-bundle-report.html
159

160
# Don't open browser
161
webpack-bundle-analyzer stats.json --mode static --no-open
162

163
# Custom title
164
webpack-bundle-analyzer stats.json --mode static --title "Production Bundle Analysis"
165
```
166

167
### JSON Mode
168

169
Generate a JSON file with bundle analysis data.
170

171
```bash { .api }
172
# JSON mode options
173
webpack-bundle-analyzer stats.json [bundleDir] \
174
  --mode json \
175
  --report <filename> \
176
  --exclude <pattern> \
177
  --log-level <level>
178
```
179

180
**Default Values:**
181
- Report filename: `report.json`
182

183
**Usage Examples:**
184

185
```bash
186
# Basic JSON report
187
webpack-bundle-analyzer stats.json --mode json
188

189
# Custom filename
190
webpack-bundle-analyzer stats.json --mode json --report bundle-data.json
191

192
# Silent mode
193
webpack-bundle-analyzer stats.json --mode json --log-level silent
194
```
195

196
### Asset Exclusion
197

198
Exclude specific assets from bundle analysis using regular expression patterns.
199

200
```bash { .api }
201
# Single exclusion pattern
202
webpack-bundle-analyzer stats.json --exclude <pattern>
203

204
# Multiple exclusion patterns
205
webpack-bundle-analyzer stats.json --exclude <pattern1> --exclude <pattern2>
206
```
207

208
**Usage Examples:**
209

210
```bash
211
# Exclude vendor files
212
webpack-bundle-analyzer stats.json --exclude vendor
213

214
# Exclude CSS files
215
webpack-bundle-analyzer stats.json --exclude "\.css$"
216

217
# Multiple exclusions
218
webpack-bundle-analyzer stats.json --exclude vendor --exclude "\.css$" --exclude runtime
219
```
220

221
### Log Level Control
222

223
Control the verbosity of CLI output.
224

225
```bash { .api }
226
# Available log levels
227
type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
228

229
# Usage
230
webpack-bundle-analyzer stats.json --log-level <level>
231
```
232

233
**Log Levels:**
234
- `debug`: Show all messages including debug information
235
- `info`: Show informational messages and above (default)
236
- `warn`: Show warnings and errors only
237
- `error`: Show errors only
238
- `silent`: Suppress all output
239

240
**Usage Examples:**
241

242
```bash
243
# Debug mode
244
webpack-bundle-analyzer stats.json --log-level debug
245

246
# Silent mode
247
webpack-bundle-analyzer stats.json --log-level silent
248

249
# Warnings and errors only
250
webpack-bundle-analyzer stats.json --log-level warn
251
```
252

253
### Size Type Selection
254

255
Choose which size metric to display by default in the visualization.
256

257
```bash { .api }
258
type SizeType = 'stat' | 'parsed' | 'gzip';
259

260
# Usage
261
webpack-bundle-analyzer stats.json --default-sizes <type>
262
```
263

264
**Size Types:**
265
- `stat`: Original file sizes from webpack stats (before transformations)
266
- `parsed`: Actual parsed bundle sizes (after minification/optimization)
267
- `gzip`: Gzipped sizes of the parsed bundles
268

269
**Usage Examples:**
270

271
```bash
272
# Show original sizes
273
webpack-bundle-analyzer stats.json --default-sizes stat
274

275
# Show parsed sizes (default)
276
webpack-bundle-analyzer stats.json --default-sizes parsed
277

278
# Show gzipped sizes
279
webpack-bundle-analyzer stats.json --default-sizes gzip
280
```