0
# Programmatic API
1

2
The Size Limit programmatic API provides functions for integrating performance budget checks into custom workflows, build systems, and automated testing.
3

4
## Capabilities
5

6
### Main API Function
7

8
The core function for running Size Limit programmatically with plugins and configuration.
9

10
```javascript { .api }
11
/**
12
 * Run Size Limit and return measurement results
13
 * @param plugins - Array of Size Limit plugins (e.g., @size-limit/webpack, @size-limit/file)
14
 * @param files - File paths array or configuration object
15
 * @returns Promise resolving to array of measurement results
16
 */
17
function sizeLimit(
18
  plugins: Function[],
19
  files: string[] | object
20
): Promise<SizeLimitResult[]>;
21

22
interface SizeLimitResult {
23
  size?: number;      // Bundle size in bytes
24
  time?: number;      // Total execution time in ms
25
  runTime?: number;   // JavaScript execution time in ms
26
  loadTime?: number;  // Loading time including network in ms
27
}
28
```
29

30
**Usage Examples:**
31

32
```javascript
33
import sizeLimit from "size-limit";
34
import filePlugin from "@size-limit/file";
35
import webpackPlugin from "@size-limit/webpack";
36
import timePlugin from "@size-limit/time";
37

38
// Basic file size measurement
39
const results = await sizeLimit([filePlugin], ["dist/bundle.js"]);
40
console.log(results); // [{ size: 12345 }]
41

42
// With bundling and time measurement
43
const results = await sizeLimit(
44
  [webpackPlugin, timePlugin, filePlugin],
45
  ["src/index.js"]
46
);
47
console.log(results);
48
// [{ size: 12345, time: 1500, runTime: 250, loadTime: 1250 }]
49

50
// Multiple files
51
const results = await sizeLimit(
52
  [filePlugin],
53
  ["dist/main.js", "dist/vendor.js"]
54
);
55
console.log(results);
56
// [{ size: 8000 }, { size: 4345 }]
57
```
58

59
### Configuration Object Format
60

61
When passing a configuration object instead of a simple file array:
62

63
```javascript { .api }
64
// Configuration object structure
65
interface SizeLimitConfig {
66
  checks: Check[];
67
}
68

69
interface Check {
70
  path: string | string[];           // File paths (required)
71
  limit?: string;                    // Size/time limit
72
  name?: string;                     // Check name
73
  brotli?: boolean;                  // Brotli compression (default: true)
74
  gzip?: boolean;                    // Use Gzip instead of Brotli
75
  webpack?: boolean;                 // Enable webpack bundling
76
  config?: string;                   // Path to custom bundler config
77
  entry?: string | string[];         // Bundler entry points
78
  import?: string | Record<string, string>; // Tree-shaking import tests
79
  ignore?: string[];                 // Files/dependencies to exclude
80
  running?: boolean;                 // Enable execution time measurement
81
  time?: TimeOptions;                // Time measurement configuration
82
  hidePassed?: boolean;              // Hide passed checks in output
83
  highlightLess?: boolean;           // Highlight improvements
84
  compareWith?: string;              // Path to stats.json for comparison
85
  uiReports?: object;               // Custom Statoscope UI reports
86
  disableModuleConcatenation?: boolean; // Disable webpack module concatenation
87
  module?: boolean;                  // Module-related option
88
  modifyWebpackConfig?: (config: any) => any; // Webpack config modifier
89
  modifyEsbuildConfig?: (config: any) => any; // ESBuild config modifier
90
}
91

92
interface TimeOptions {
93
  networkSpeed?: string;    // Network speed (default: "50 kB")
94
  latency: string;         // Network latency simulation (default: "0")
95
  loadingMessage?: string; // Loading message (default: "on slow 3G")
96
}
97
```
98

99
**Usage Examples:**
100

101
```javascript
102
// Advanced configuration
103
const results = await sizeLimit(
104
  [webpackPlugin, timePlugin, filePlugin],
105
  {
106
    checks: [
107
      {
108
        path: ["src/app.js"],
109
        limit: "100 kB",
110
        name: "Main Bundle",
111
        webpack: true,
112
        time: {
113
          networkSpeed: "3G",
114
          latency: "400ms",
115
          loadingMessage: "on 3G connection"
116
        }
117
      },
118
      {
119
        path: ["src/worker.js"],
120
        limit: "50 kB",
121
        name: "Web Worker",
122
        brotli: false,
123
        gzip: true
124
      }
125
    ]
126
  }
127
);
128
```
129

130
### Import Processing Utility
131

132
Utility function for handling import statements in tree-shaking analysis.
133

134
```javascript { .api }
135
/**
136
 * Process import configuration and create temporary entry files
137
 * @param check - Check configuration object with import property
138
 * @param output - Output directory for generated entry files
139
 * @returns Promise that resolves when processing is complete
140
 */
141
async function processImport(check: Check, output: string): Promise<void>;
142
```
143

144
**Usage Examples:**
145

146
```javascript
147
import { processImport } from "size-limit";
148

149
// Tree-shaking test configuration
150
const check = {
151
  path: ["src/index.js"],
152
  import: {
153
    "my-library": "{ specificFunction }",
154
    "another-lib": "*"
155
  }
156
};
157

158
// Process imports and generate entry files
159
await processImport(check, "./temp-output");
160
// Creates entry files testing specific imports
161
```
162

163
### Error Handling
164

165
Size Limit provides structured error handling for configuration and runtime issues.
166

167
```javascript { .api }
168
class SizeLimitError extends Error {
169
  constructor(type: string, ...args: any[]);
170
  name: "SizeLimitError";
171
  example?: string;  // Configuration example for setup errors
172
}
173
```
174

175
**Common Error Types:**
176

177
```javascript
178
import { SizeLimitError } from "size-limit";
179

180
try {
181
  const results = await sizeLimit([filePlugin], []);
182
} catch (error) {
183
  if (error instanceof SizeLimitError) {
184
    console.error(`Size Limit Error: ${error.message}`);
185
    if (error.example) {
186
      console.log("Example configuration:", error.example);
187
    }
188
  }
189
}
190
```
191

192
## Plugin Integration
193

194
The programmatic API requires plugins to be explicitly provided:
195

196
**Available Official Plugins:**
197
- `@size-limit/file` - Basic file size measurement
198
- `@size-limit/webpack` - Webpack bundling and analysis
199
- `@size-limit/esbuild` - ESBuild bundling
200
- `@size-limit/time` - Execution time measurement in browser
201
- `@size-limit/webpack-css` - CSS support for webpack
202
- `@size-limit/webpack-why` - Bundle analysis and visualization
203
- `@size-limit/esbuild-why` - ESBuild bundle analysis
204

205
**Plugin Loading Example:**
206

207
```javascript
208
import sizeLimit from "size-limit";
209

210
// Dynamic plugin loading
211
const plugins = [];
212
if (needsBundling) {
213
  const webpackPlugin = await import("@size-limit/webpack");
214
  plugins.push(webpackPlugin.default);
215
}
216
if (needsTiming) {
217
  const timePlugin = await import("@size-limit/time");
218
  plugins.push(timePlugin.default);
219
}
220

221
// Always include file plugin for size measurement
222
const filePlugin = await import("@size-limit/file");
223
plugins.push(filePlugin.default);
224

225
const results = await sizeLimit(plugins, files);
226
```