0
# CLI Utility
1
2
Command-line interface for processing and combining multiple visualization data files into unified analysis.
3
4
The CLI utility does not require imports as it's accessed directly as a binary, but processes data files in the `VisualizerData` format.
5
6
## Capabilities
7
8
### CLI Binary
9
10
Standalone command-line tool for combining multiple JSON stats files into a single visualization.
11
12
```typescript { .api }
13
// CLI binary available at: rollup-plugin-visualizer
14
// Installation provides global binary access
15
```
16
17
The CLI utility is installed as a binary when you install the package and can be accessed directly from the command line. It's particularly useful for combining analysis from multiple build configurations or comparing different builds.
18
19
**Basic Usage:**
20
21
```bash
22
# Process single stats file
23
rollup-plugin-visualizer stats.json
24
25
# Combine multiple stats files
26
rollup-plugin-visualizer stats1.json stats2.json stats3.json
27
28
# Custom output and template
29
rollup-plugin-visualizer --filename combined-stats.html --template network *.json
30
31
# Open result automatically
32
rollup-plugin-visualizer --open --template treemap build-*/stats.json
33
```
34
35
### CLI Options
36
37
Command-line options for customizing the output and behavior.
38
39
```typescript { .api }
40
interface CliOptions {
41
/** Output file name (default: "./stats.html") */
42
filename: string;
43
44
/** Output file title (default: "Rollup Visualizer") */
45
title: string;
46
47
/** Template type for visualization */
48
template: TemplateType;
49
50
/** Process files as sourcemap-based data (default: false) */
51
sourcemap: boolean;
52
53
/** Open generated file in default application (default: false) */
54
open: boolean;
55
}
56
```
57
58
**CLI Option Details:**
59
60
- **`--filename`**: Specifies the output file path and name
61
- **`--title`**: Sets the HTML title for the generated visualization
62
- **`--template`**: Chooses visualization type (sunburst, treemap, network, raw-data, list, flamegraph)
63
- **`--sourcemap`**: Process input files as sourcemap-based visualization data
64
- **`--open`**: Automatically opens the generated file in the default browser/application
65
66
**Usage Examples:**
67
68
```bash
69
# Generate network diagram with custom title
70
rollup-plugin-visualizer \
71
--filename "dependency-analysis.html" \
72
--title "Project Dependency Analysis" \
73
--template network \
74
build-stats.json
75
76
# Create combined treemap from multiple builds
77
rollup-plugin-visualizer \
78
--filename "combined-analysis.html" \
79
--template treemap \
80
--open \
81
dev-stats.json prod-stats.json
82
83
# Export raw data for further processing
84
rollup-plugin-visualizer \
85
--filename "combined-data.json" \
86
--template raw-data \
87
stats/*.json
88
89
# Generate list format for version control
90
rollup-plugin-visualizer \
91
--filename "bundle-manifest.yml" \
92
--template list \
93
production-stats.json
94
```
95
96
### CLI Workflow Integration
97
98
Common patterns for integrating the CLI into development and CI/CD workflows.
99
100
**Multi-Configuration Analysis:**
101
102
```bash
103
# Build different configurations
104
npm run build:dev # Generates dev-stats.json
105
npm run build:prod # Generates prod-stats.json
106
107
# Combine for comparison
108
rollup-plugin-visualizer \
109
--filename "build-comparison.html" \
110
--template treemap \
111
--title "Dev vs Prod Bundle Analysis" \
112
dev-stats.json prod-stats.json
113
```
114
115
**CI/CD Integration:**
116
117
```bash
118
#!/bin/bash
119
# In CI/CD pipeline
120
121
# Generate stats during build
122
npm run build -- --plugin-visualizer-template=raw-data
123
124
# Combine with historical data
125
rollup-plugin-visualizer \
126
--filename "trend-analysis.html" \
127
--template network \
128
current-stats.json \
129
artifacts/previous-stats.json
130
131
# Archive for trend analysis
132
cp current-stats.json "artifacts/stats-$(date +%Y%m%d).json"
133
```
134
135
**Development Workflow:**
136
137
```bash
138
# Development script combining multiple entry points
139
rollup-plugin-visualizer \
140
--filename "dev-analysis.html" \
141
--template sunburst \
142
--open \
143
main-stats.json \
144
worker-stats.json \
145
vendor-stats.json
146
```
147
148
### Data File Compatibility
149
150
The CLI processes JSON files generated by the plugin's `raw-data` template.
151
152
```typescript { .api }
153
// Input file format (generated by template: "raw-data")
154
interface InputStatsFile {
155
version: number;
156
tree: ModuleTree;
157
nodeParts: Record<ModuleUID, ModulePart>;
158
nodeMetas: Record<ModuleUID, ModuleMeta>;
159
env: { [key: string]: unknown };
160
options: { gzip: boolean; brotli: boolean; sourcemap: boolean };
161
}
162
```
163
164
**Generating Compatible Files:**
165
166
```typescript
167
// In rollup.config.js - generate data files for CLI
168
visualizer({
169
filename: 'build-stats.json',
170
template: 'raw-data'
171
})
172
```
173
174
**Version Compatibility:**
175
176
The CLI checks version compatibility between data files and will skip files with incompatible versions, logging warnings for skipped files.
177
178
### Error Handling
179
180
Common error scenarios and troubleshooting:
181
182
```bash
183
# No input files provided
184
rollup-plugin-visualizer
185
# Error: Empty file list
186
187
# Invalid JSON files
188
rollup-plugin-visualizer invalid.json
189
# Error: Failed to parse JSON
190
191
# Version mismatch
192
rollup-plugin-visualizer old-format.json
193
# Warning: Version in old-format.json is not supported (1). Current version 2. Skipping...
194
195
# File not found
196
rollup-plugin-visualizer missing.json
197
# Error: ENOENT: no such file or directory
198
```
199
200
### Help and Documentation
201
202
```bash
203
# Display help information
204
rollup-plugin-visualizer --help
205
206
# Lists all available options and usage examples
207
```
208
209
The CLI provides comprehensive help documentation including all available options, template choices, and usage examples.