Size Limit CLI Tool

12.1.0 · active · verified Wed Apr 22

Size Limit is a performance budget command-line interface (CLI) tool for JavaScript projects, designed to prevent web performance regressions. It integrates into CI/CD pipelines (like GitHub Actions, Travis CI, Circle CI) to automatically check bundle size against predefined limits on every commit or pull request. The tool supports ES modules and tree-shaking, providing modular plugins to adapt to various project setups, from large applications to small npm libraries. Rather than just raw bytes, it can calculate the estimated download and execution time for end-users, incorporating all dependencies and polyfills. The current stable version is 12.1.0, with an active release cadence involving frequent patch and minor updates, and major versions released as necessary for breaking changes or significant feature additions.

Common errors

```
Error: Node.js 18 is not supported. Please upgrade to Node.js 20 or higher.
```
cause Attempting to run Size Limit v12.0.0 or later on an unsupported Node.js environment.

fix Update your Node.js version to 20 or 22 (or higher) using a version manager like `nvm` or by updating your environment's Node.js installation.
```
Cannot read config. Make sure that size-limit is mentioned in package.json
```
cause Size Limit could not find a configuration file (`.size-limit.js`, `.size-limit.json`, etc.) or it's misconfigured in `package.json`.

fix Ensure you have a valid `.size-limit.js` or `.size-limit.json` file in your project root, or specify its path using `size-limit --config ./path/to/config.js`.
```
Error: Cannot find module 'jiti'
```
cause Your `.size-limit.js` configuration file uses advanced JavaScript features (like top-level await) that require `jiti`, but `jiti` is not installed as it's now an optional peer dependency.

fix Install `jiti` explicitly as a dependency: `npm install jiti` or `yarn add jiti`.

Warnings

breaking Node.js 18 is no longer supported starting with Size Limit v12.0.0. Projects using older Node.js versions must upgrade to Node.js 20 or newer.
Fix: Upgrade your Node.js environment to version 20.0.0 or higher. For CI/CD, ensure your build pipelines are configured to use a supported Node.js version.
gotcha The `jiti` package, used for loading advanced JavaScript configuration files (e.g., with top-level await), was moved to an optional peer dependency in v12.0.0. If you encounter issues loading complex `.js` config files, you may need to install it manually.
Fix: If your `.size-limit.js` configuration fails to load due to `jiti`-related errors, install it explicitly: `npm install jiti` or `yarn add jiti`.
gotcha Size Limit's default behavior relies on Webpack for bundling and analysis. For projects that do not use Webpack (e.g., Rollup, esbuild, or bare JavaScript files), remember to set `webpack: false` in your configuration for relevant entries to get accurate results.
Fix: In your `.size-limit.js` configuration, add `webpack: false` to any entry that should not be processed by Webpack, or use a specific plugin like `esbuild` if applicable.

Install

npm install size-limit npm
yarn add size-limit yarn
pnpm add size-limit pnpm

Imports

Config
wrong:
```
import { Config } from 'size-limit'
```
correct:
```
import { type Config } from 'size-limit'
```
This is a TypeScript type import, primarily used for type-checking your `.size-limit.ts` configuration file. Use `import type` to ensure it's removed at compile time.
run
```
import { run } from 'size-limit/run'
```
Imports the core function to run Size Limit programmatically from a JavaScript or TypeScript file. This is useful for custom integrations beyond the standard CLI usage.
createReporter
```
import { createReporter } from 'size-limit/create-reporter'
```
Used to create custom reporters for programmatic Size Limit runs, allowing for tailored output formats or integration with other reporting systems.

Quickstart

Demonstrates a basic `.size-limit.js` configuration file to define bundle size limits for multiple files or patterns, and how to execute the tool via `npx`.

/* .size-limit.js */
/** @type {import('size-limit').Config} */
module.exports = [
  {
    path: 'dist/main.js',
    limit: '10 kB',
    name: 'Main Bundle'
  },
  {
    path: 'dist/*.css',
    limit: '2 kB',
    name: 'CSS Stylesheets'
  },
  {
    path: ['dist/vendor.js', 'dist/utils.js'],
    limit: '5 kB',
    webpack: false, // For non-webpack bundles
    gzip: true
  }
];

// To run Size Limit after setting up the config:
// npx size-limit

view raw JSON →