0
# CLI Interface
1

2
The Size Limit CLI provides a command-line interface for running performance budget checks in development and CI environments.
3

4
## Capabilities
5

6
### Basic Commands
7

8
The main CLI command with various options for different use cases.
9

10
```bash { .api }
11
# Basic usage
12
size-limit
13

14
# Common options
15
size-limit [options]
16

17
# Key options:
18
--json                    # Output results in JSON format
19
--silent                  # Silent mode (no console output except errors)
20
--watch                   # Watch mode for file changes during development
21
--why                     # Bundle analysis mode with detailed breakdown
22
--config FILE             # Use specific configuration file
23
--limit SIZE              # Override size limit for all checks
24
--save-bundle DIR         # Save bundle to directory for analysis
25
--clean-dir               # Clean bundle directory (requires --save-bundle)
26
--hide-passed             # Hide passed checks in output
27
--highlight-less          # Highlight improvements
28
--compare-with FILE       # Compare with previous stats.json (requires --why)
29
--debug                   # Show internal configs for issue report
30
--help                    # Show help information
31
--version                 # Show version information
32
```
33

34
**Usage Examples:**
35

36
```bash
37
# Basic size check using package.json configuration
38
size-limit
39

40
# JSON output for CI integration
41
size-limit --json
42

43
# Silent mode for scripts
44
size-limit --silent
45

46
# Watch mode for development
47
size-limit --watch
48

49
# Bundle analysis
50
size-limit --why
51

52
# Use specific configuration file
53
size-limit --config .size-limit.json
54

55
# Override size limit for all checks
56
size-limit --limit "50 kB"
57

58
# Save bundle for analysis
59
size-limit --save-bundle ./analysis-output
60

61
# Clean and save bundle
62
size-limit --save-bundle ./analysis-output --clean-dir
63

64
# Bundle analysis with comparison
65
size-limit --why --compare-with previous-stats.json
66

67
# Hide passed checks in output
68
size-limit --hide-passed
69

70
# Highlight improvements
71
size-limit --highlight-less
72

73
# Debug mode
74
size-limit --debug
75
```
76

77
### Output Formats
78

79
The CLI supports different output formats for various use cases.
80

81
#### Console Output (Default)
82

83
```bash { .api }
84
# Standard console output shows:
85
# - Check names and file paths
86
# - Size measurements with limits
87
# - Pass/fail status with color coding
88
# - Time measurements when enabled
89
# - Summary of results
90

91
size-limit
92
# Example output:
93
#   Package size: 12.34 kB with all dependencies, minified and gzipped
94
#   Size limit:   15 kB
95
#   
96
#   Running time: 0.1 s
97
#   Time limit:   1 s
98
#   
99
#   ✓ Passed
100
```
101

102
#### JSON Output
103

104
```bash { .api }
105
# JSON output for programmatic consumption
106
size-limit --json
107

108
# Example JSON structure:
109
# [
110
#   {
111
#     "name": "Main Bundle",
112
#     "passed": true,
113
#     "size": 12636,
114
#     "sizeLimit": 15360,
115
#     "running": 100,
116
#     "loading": 250
117
#   }
118
# ]
119
```
120

121
### Configuration Sources
122

123
The CLI automatically detects configuration from multiple sources.
124

125
```bash { .api }
126
# Configuration priority (highest to lowest):
127
# 1. .size-limit.js (dynamic configuration)
128
# 2. .size-limit.json
129
# 3. package.json "size-limit" field
130
# 4. Command line arguments
131
```
132

133
**Configuration Examples:**
134

135
```json
136
// package.json
137
{
138
  "size-limit": [
139
    {
140
      "path": "dist/bundle.js",
141
      "limit": "10 kB"
142
    },
143
    {
144
      "path": "dist/worker.js",
145
      "limit": "5 kB",
146
      "webpack": false
147
    }
148
  ]
149
}
150
```
151

152
```json
153
// .size-limit.json
154
[
155
  {
156
    "name": "Main Bundle",
157
    "path": "dist/app.js",
158
    "limit": "100 kB",
159
    "running": false
160
  }
161
]
162
```
163

164
```javascript
165
// .size-limit.js
166
module.exports = [
167
  {
168
    name: "Dynamic Config",
169
    path: process.env.BUNDLE_PATH || "dist/bundle.js",
170
    limit: "50 kB",
171
    modifyWebpackConfig: (config) => {
172
      // Custom webpack modifications
173
      return config;
174
    }
175
  }
176
];
177
```
178

179
### Plugin Detection
180

181
The CLI automatically detects and loads available plugins from dependencies.
182

183
```bash { .api }
184
# Plugin detection rules:
185
# - Scans package.json dependencies and devDependencies  
186
# - Loads plugins matching @size-limit/* pattern
187
# - Loads plugins matching size-limit-* pattern
188
# - Plugins are loaded automatically based on configuration needs
189
```
190

191
**Plugin Installation:**
192

193
```bash
194
# Install core plugins
195
npm install --save-dev @size-limit/file
196
npm install --save-dev @size-limit/webpack
197
npm install --save-dev @size-limit/time
198

199
# Install preset (includes multiple plugins)
200
npm install --save-dev @size-limit/preset-app
201
npm install --save-dev @size-limit/preset-big-lib
202
npm install --save-dev @size-limit/preset-small-lib
203
```
204

205
### Watch Mode
206

207
Development mode that monitors files for changes and re-runs checks.
208

209
```bash { .api }
210
# Watch mode for development
211
size-limit --watch
212

213
# Features:
214
# - Monitors configured files for changes
215
# - Debounced re-execution (200ms delay)
216
# - Real-time feedback during development
217
# - Throttled to prevent excessive runs
218
```
219

220
### Bundle Analysis
221

222
Detailed analysis mode for understanding bundle composition.
223

224
```bash { .api }
225
# Bundle analysis requires @size-limit/webpack-why or @size-limit/esbuild-why
226
size-limit --why
227

228
# Features:
229
# - Detailed bundle breakdown
230
# - Dependency analysis
231
# - Tree-shaking effectiveness
232
# - Module size contributions
233
# - Interactive reports (when supported)
234
```
235

236
### CI Integration
237

238
The CLI is designed for seamless CI integration.
239

240
```bash { .api }
241
# CI-friendly features:
242
# - Exit codes: 0 for pass, 1 for fail
243
# - JSON output for parsing
244
# - Silent mode for clean logs
245
# - No interactive prompts
246
```
247

248
**CI Examples:**
249

250
```yaml
251
# GitHub Actions
252
- name: Check bundle size
253
  run: npx size-limit --json > size-report.json
254

255
# Check exit code
256
- name: Validate size limits
257
  run: npx size-limit --silent
258
```
259

260
```bash
261
# Shell script integration
262
if npx size-limit --silent; then
263
  echo "Size limits passed"
264
else
265
  echo "Size limits exceeded"
266
  exit 1
267
fi
268
```
269

270
### Error Handling
271

272
The CLI provides clear error messages and helpful suggestions.
273

274
```bash { .api }
275
# Common error scenarios:
276
# - Missing configuration
277
# - Plugin dependencies not installed  
278
# - Invalid configuration format
279
# - File path errors
280
# - Limit exceeded errors
281

282
# Error output includes:
283
# - Clear error descriptions
284
# - Configuration examples
285
# - Plugin installation suggestions
286
# - Helpful debugging information
287
```
288

289
**Error Examples:**
290

291
```bash
292
# Missing configuration
293
size-limit
294
# Error: Create Size Limit config in package.json
295
# Example configuration shown
296

297
# Missing plugin
298
size-limit
299
# Error: Add @size-limit/webpack plugin to Size Limit
300
# Installation command provided
301
```
302

303
### Global Installation
304

305
Size Limit can be installed globally for system-wide use.
306

307
```bash { .api }
308
# Global installation
309
npm install -g size-limit
310

311
# Usage from anywhere
312
cd /path/to/project
313
size-limit
314

315
# Or use npx for one-time execution
316
npx size-limit
317
```