0
# Configuration
1

2
Size Limit provides flexible configuration options supporting multiple formats, validation, and environment-specific setups.
3

4
## Capabilities
5

6
### Configuration Sources
7

8
Size Limit loads configuration from multiple sources with a defined priority order.
9

10
```javascript { .api }
11
// Configuration priority (highest to lowest):
12
// 1. .size-limit.js (dynamic configuration with functions)
13
// 2. .size-limit.json (static JSON configuration)  
14
// 3. package.json "size-limit" field
15
// 4. Programmatic API configuration object
16
```
17

18
### Check Configuration
19

20
Each size check is defined by a configuration object with multiple options.
21

22
```javascript { .api }
23
interface Check {
24
  // Required
25
  path: string | string[];           // File paths or glob patterns
26
  
27
  // Limits
28
  limit?: string;                    // Size or time limit (e.g., "100 kB", "500 ms")
29
  
30
  // Identification
31
  name?: string;                     // Check name for multi-section configs
32
  
33
  // Compression
34
  brotli?: boolean;                  // Enable Brotli compression (default: true)
35
  gzip?: boolean;                    // Use Gzip instead of Brotli
36
  
37
  // Bundling
38
  webpack?: boolean;                 // Enable webpack bundling (default: true)
39
  config?: string;                   // Path to custom webpack/bundler config
40
  entry?: string | string[];         // Custom bundler entry points
41
  
42
  // Tree-shaking and Analysis
43
  import?: string | Record<string, string>; // Partial import testing
44
  ignore?: string[];                 // Files/dependencies to exclude
45
  
46
  // Time Measurement
47
  running?: boolean;                 // Enable execution time measurement (default: true)
48
  time?: TimeOptions;                // Time measurement configuration
49
  
50
  // Advanced Options
51
  module?: boolean;                  // Module-related option
52
  hidePassed?: boolean;              // Hide passed checks in output
53
  highlightLess?: boolean;           // Highlight improvements
54
  compareWith?: string;              // Path to stats.json for comparison
55
  uiReports?: object;               // Custom Statoscope UI reports
56
  disableModuleConcatenation?: boolean; // Disable webpack module concatenation
57
  
58
  // Configuration Modifiers (JS config only)
59
  modifyWebpackConfig?: (config: any) => any; // Webpack config modifier
60
  modifyEsbuildConfig?: (config: any) => any; // ESBuild config modifier
61
}
62

63
interface TimeOptions {
64
  networkSpeed?: string;    // Network speed (default: "50 kB")
65
  latency: string;         // Network latency simulation (default: "0")
66
  loadingMessage?: string; // Loading message (default: "on slow 3G")
67
}
68

69
type SizeLimitConfig = Check[];
70
```
71

72
### Package.json Configuration
73

74
The most common configuration method using the package.json file.
75

76
**Usage Examples:**
77

78
```json
79
{
80
  "name": "my-package",
81
  "size-limit": [
82
    {
83
      "path": "dist/bundle.js",
84
      "limit": "10 kB"
85
    }
86
  ]
87
}
88
```
89

90
```json
91
{
92
  "size-limit": [
93
    {
94
      "name": "Main Bundle",
95
      "path": "dist/app.js",
96
      "limit": "100 kB",
97
      "webpack": true,
98
      "running": false
99
    },
100
    {
101
      "name": "Web Worker",
102
      "path": "dist/worker.js", 
103
      "limit": "50 kB",
104
      "webpack": false,
105
      "brotli": false,
106
      "gzip": true
107
    },
108
    {
109
      "name": "Library Export",
110
      "path": "dist/lib.js",
111
      "import": "{ createLibrary }",
112
      "limit": "25 kB"
113
    }
114
  ]
115
}
116
```
117

118
### JSON Configuration File
119

120
Static configuration in a dedicated JSON file.
121

122
**.size-limit.json:**
123

124
```json
125
[
126
  {
127
    "name": "Application Bundle",
128
    "path": ["dist/app.js", "dist/vendor.js"],
129
    "limit": "200 kB",
130
    "time": {
131
      "networkSpeed": "3G",
132
      "latency": "400ms",
133
      "loadingMessage": "on 3G connection"
134
    }
135
  },
136
  {
137
    "name": "Critical CSS",
138
    "path": "dist/critical.css",
139
    "limit": "5 kB",
140
    "webpack": false
141
  }
142
]
143
```
144

145
### JavaScript Configuration File
146

147
Dynamic configuration with functions and environment variables.
148

149
**.size-limit.js:**
150

151
```javascript
152
import { join } from 'node:path';
153

154
export default [
155
  {
156
    name: "Dynamic Bundle",
157
    path: process.env.NODE_ENV === 'production' 
158
      ? "dist/app.min.js" 
159
      : "dist/app.js",
160
    limit: process.env.SIZE_LIMIT || "100 kB",
161
    modifyWebpackConfig: (config) => {
162
      // Add custom webpack plugins
163
      config.plugins.push(new MyCustomPlugin());
164
      return config;
165
    }
166
  },
167
  {
168
    name: "Tree-shaking Test",
169
    path: "src/index.js",
170
    import: {
171
      "lodash": "{ debounce }",
172
      "./utils": "{ helper1, helper2 }"
173
    },
174
    limit: "15 kB"
175
  }
176
];
177
```
178

179
### Path Configuration
180

181
File path specifications support various formats and patterns.
182

183
```javascript { .api }
184
// Path formats
185
interface PathOptions {
186
  // Single file
187
  path: "dist/bundle.js";
188
  
189
  // Multiple files  
190
  path: ["dist/app.js", "dist/vendor.js"];
191
  
192
  // Glob patterns
193
  path: "dist/*.js";
194
  
195
  // Complex glob patterns
196
  path: ["dist/app-*.js", "!dist/app-test.js"];
197
  
198
  // Directory patterns
199
  path: "dist/**/*.js";
200
}
201
```
202

203
**Path Examples:**
204

205
```json
206
{
207
  "size-limit": [
208
    {
209
      "name": "All JS files",
210
      "path": "dist/**/*.js",
211
      "limit": "500 kB"
212
    },
213
    {
214
      "name": "Specific files",
215
      "path": ["dist/main.js", "dist/polyfills.js"],
216
      "limit": "200 kB"
217
    },
218
    {
219
      "name": "Exclude test files",
220
      "path": ["src/**/*.js", "!src/**/*.test.js"],
221
      "limit": "300 kB"
222
    }
223
  ]
224
}
225
```
226

227
### Limit Configuration
228

229
Size and time limits support various units and formats.
230

231
```javascript { .api }
232
// Limit format examples
233
interface LimitOptions {
234
  // Size limits
235
  limit: "100 B";      // Bytes
236
  limit: "10 kB";      // Kilobytes  
237
  limit: "5 MB";       // Megabytes
238
  limit: "1.5 kB";     // Decimal values
239
  
240
  // Time limits
241
  limit: "500 ms";     // Milliseconds
242
  limit: "2 s";        // Seconds
243
  limit: "1.5 s";      // Decimal seconds
244
}
245
```
246

247
**Limit Examples:**
248

249
```json
250
{
251
  "size-limit": [
252
    {
253
      "path": "dist/tiny-lib.js",
254
      "limit": "5 kB"
255
    },
256
    {
257
      "path": "dist/app.js", 
258
      "limit": "100 kB"
259
    },
260
    {
261
      "path": "dist/heavy-feature.js",
262
      "limit": "2 s",
263
      "time": {
264
        "networkSpeed": "slow 3G"
265
      }
266
    }
267
  ]
268
}
269
```
270

271
### Import Testing Configuration
272

273
Tree-shaking and partial import testing configuration.
274

275
```javascript { .api }
276
// Import testing formats
277
interface ImportOptions {
278
  // Single import
279
  import: "{ specificFunction }";
280
  
281
  // All exports
282
  import: "*";
283
  
284
  // Multiple files with specific imports
285
  import: {
286
    "library-name": "{ func1, func2 }",
287
    "./local-module": "{ helper }",
288
    "another-lib": "*"
289
  };
290
}
291
```
292

293
**Import Examples:**
294

295
```json
296
{
297
  "size-limit": [
298
    {
299
      "name": "Lodash tree-shaking",
300
      "path": "src/index.js",
301
      "import": "{ debounce, throttle }",
302
      "limit": "10 kB"
303
    },
304
    {
305
      "name": "Full library import",
306
      "path": "src/heavy-usage.js", 
307
      "import": "*",
308
      "limit": "200 kB"
309
    },
310
    {
311
      "name": "Multi-library test",
312
      "path": "src/app.js",
313
      "import": {
314
        "react": "{ useState, useEffect }",
315
        "lodash": "{ map, filter }",
316
        "./utils": "*"
317
      },
318
      "limit": "150 kB"
319
    }
320
  ]
321
}
322
```
323

324
### Environment-Specific Configuration
325

326
Configuration can adapt to different environments and build contexts.
327

328
```javascript
329
// .size-limit.js with environment handling
330
const isDevelopment = process.env.NODE_ENV === 'development';
331
const isCI = process.env.CI === 'true';
332

333
export default [
334
  {
335
    name: "Main Bundle",
336
    path: isDevelopment ? "src/index.js" : "dist/bundle.js",
337
    limit: isDevelopment ? "200 kB" : "100 kB",
338
    webpack: !isDevelopment,
339
    running: !isCI, // Skip time measurement in CI
340
    time: isDevelopment ? undefined : {
341
      networkSpeed: "3G",
342
      latency: "400ms"
343
    }
344
  }
345
];
346
```
347

348
### Validation and Error Handling
349

350
Size Limit validates configuration and provides helpful error messages.
351

352
```javascript { .api }
353
// Configuration validation rules:
354
// - path is required and must be string or array of strings
355
// - limit must follow format: number + space + unit
356
// - entry must be string or array of strings  
357
// - Plugin-specific options validated against available plugins
358
// - Circular dependency detection
359
// - File existence validation
360
```
361

362
**Common Configuration Errors:**
363

364
```json
365
// Invalid: missing path
366
{
367
  "size-limit": [
368
    {
369
      "limit": "10 kB"
370
    }
371
  ]
372
}
373

374
// Invalid: wrong limit format  
375
{
376
  "size-limit": [
377
    {
378
      "path": "dist/app.js",
379
      "limit": "10kb"  // Should be "10 kB"
380
    }
381
  ]
382
}
383

384
// Invalid: entry without webpack
385
{
386
  "size-limit": [
387
    {
388
      "path": "src/index.js",
389
      "entry": "custom-entry.js",
390
      "webpack": false
391
    }
392
  ]
393
}
394
```