0
# Size Limit
1

2
Size Limit is a comprehensive performance budget tool for JavaScript applications and libraries that monitors bundle size and execution time. It provides both a CLI tool for CI integration and a programmatic API for custom workflows, with a modular plugin architecture supporting webpack, esbuild, and other bundlers.
3

4
## Package Information
5

6
- **Package Name**: size-limit
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install --save-dev size-limit` (requires plugins for functionality)
10

11
## Core Imports
12

13
```javascript
14
import sizeLimit from "size-limit";
15
import { processImport, SizeLimitError } from "size-limit";
16
```
17

18
**Note**: Size Limit is an ES module only package. CommonJS `require()` is not supported.
19

20
## Basic Usage
21

22
### CLI Tool
23

24
```bash
25
# Install with preset for typical use cases
26
npm install --save-dev @size-limit/preset-small-lib
27

28
# Or install specific plugins
29
npm install --save-dev size-limit @size-limit/file @size-limit/webpack
30

31
# Run size check
32
size-limit
33

34
# Run with specific config
35
size-limit --config .size-limit.json
36

37
# Watch mode for development
38
size-limit --watch
39

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

44
### Programmatic API
45

46
```javascript
47
import sizeLimit from "size-limit";
48
import filePlugin from "@size-limit/file";
49
import webpackPlugin from "@size-limit/webpack";
50

51
// Basic usage with plugins
52
const results = await sizeLimit(
53
  [filePlugin, webpackPlugin],
54
  ["dist/bundle.js"]
55
);
56

57
console.log(results); // [{ size: 12345 }]
58

59
// With configuration object
60
const results = await sizeLimit(
61
  [filePlugin, webpackPlugin],
62
  {
63
    checks: [
64
      {
65
        path: ["dist/bundle.js"],
66
        limit: "10 kB"
67
      }
68
    ]
69
  }
70
);
71
```
72

73
## Architecture
74

75
Size Limit is built around several key components:
76

77
- **Core API**: Main `sizeLimit()` function for programmatic usage
78
- **CLI Tool**: Command-line interface with argument parsing and reporting
79
- **Plugin System**: Modular architecture with plugins for different bundlers and measurements
80
- **Configuration System**: Flexible config loading from package.json, files, or programmatic objects
81
- **Reporter System**: Output formatting for console, JSON, and CI integration
82

83
## Capabilities
84

85
### Programmatic API
86

87
Core programmatic interface for integrating Size Limit into custom workflows and build systems.
88

89
```javascript { .api }
90
/**
91
 * Run Size Limit and return the result
92
 * @param plugins - Array of Size Limit plugins like @size-limit/webpack
93
 * @param files - File paths array or internal config object
94
 * @returns Promise resolving to array of measurement results
95
 */
96
function sizeLimit(
97
  plugins: Function[],
98
  files: string[] | object
99
): Promise<SizeLimitResult[]>;
100
```
101

102
[Programmatic API](./programmatic-api.md)
103

104
### CLI Interface
105

106
Command-line tool for running Size Limit checks in development and CI environments.
107

108
```bash { .api }
109
# Basic commands
110
size-limit [options]
111

112
# Key options
113
--json          # Output results in JSON format
114
--silent        # Silent mode (no console output)
115
--watch         # Watch mode for file changes
116
--why           # Bundle analysis mode
117
--clean-dir     # Clean bundle directory before analysis
118
```
119

120
[CLI Interface](./cli-interface.md)
121

122
### Configuration System
123

124
Flexible configuration system supporting multiple formats and validation options.
125

126
```javascript { .api }
127
// Configuration object structure
128
interface Check {
129
  path: string | string[];           // File paths (required)
130
  limit?: string;                    // Size/time limit
131
  name?: string;                     // Check name
132
  brotli?: boolean;                  // Brotli compression (default: true)
133
  gzip?: boolean;                    // Gzip compression
134
  webpack?: boolean;                 // Enable webpack bundling
135
  config?: string;                   // Custom bundler config path
136
  entry?: string | string[];         // Bundler entry points
137
  import?: string | Record<string, string>; // Tree-shaking tests
138
  ignore?: string[];                 // Exclude patterns
139
  running?: boolean;                 // Execution time measurement
140
  time?: TimeOptions;                // Time measurement options
141
  hidePassed?: boolean;              // Hide passed checks in output
142
  highlightLess?: boolean;           // Highlight improvements
143
  compareWith?: string;              // Path to stats.json for comparison
144
  uiReports?: object;               // Custom Statoscope UI reports
145
  disableModuleConcatenation?: boolean; // Disable webpack module concatenation
146
  module?: boolean;                  // Module-related option
147
  modifyWebpackConfig?: (config: any) => any; // Webpack config modifier
148
  modifyEsbuildConfig?: (config: any) => any; // ESBuild config modifier
149
}
150

151
type SizeLimitConfig = Check[];
152
```
153

154
[Configuration](./configuration.md)
155

156
### Plugin System
157

158
Modular plugin architecture for different bundlers, measurements, and analysis tools.
159

160
```javascript { .api }
161
// Plugin interface (for plugin developers)
162
interface Plugin {
163
  name: string;
164
  before?(config: object, check: Check): Promise<void>;
165
  step0?(config: object, check: Check): Promise<void>;
166
  // ... step1 through step100
167
  finally?(config: object, check: Check): Promise<void>;
168
  wait0?: string;  // Progress message
169
  // ... wait1 through wait100
170
}
171
```
172

173
[Plugin System](./plugin-system.md)
174

175
### Error Handling
176

177
Structured error handling with specific error types and helpful messages.
178

179
```javascript { .api }
180
class SizeLimitError extends Error {
181
  constructor(type: string, ...args: any[]);
182
  name: "SizeLimitError";
183
  example?: string;  // Configuration example for certain error types
184
}
185
```
186

187
[Error Handling](./error-handling.md)
188

189
## Types
190

191
```javascript { .api }
192
// Main API types
193
interface TimeOptions {
194
  networkSpeed?: string;    // Default: "50 kB"
195
  latency: string;         // Network latency simulation
196
  loadingMessage?: string; // Default: "on slow 3G"
197
}
198

199
// Result object structure
200
interface SizeLimitResult {
201
  size?: number;      // Bundle size in bytes
202
  time?: number;      // Total execution time
203
  runTime?: number;   // JavaScript execution time
204
  loadTime?: number;  // Loading time including network
205
}
206
```