{"id":17365,"library":"size-limit","title":"Size Limit CLI Tool","description":"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.","status":"active","version":"12.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/ai/size-limit","tags":["javascript","budget","cli","esm","performance","performance budget","size-limit","typescript"],"install":[{"cmd":"npm install size-limit","lang":"bash","label":"npm"},{"cmd":"yarn add size-limit","lang":"bash","label":"yarn"},{"cmd":"pnpm add size-limit","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for loading JavaScript configuration files with features like top-level await. It became an optional peer dependency in v12.0.0, meaning it's not strictly required for all use cases, but may be needed for advanced configuration.","package":"jiti","optional":true}],"imports":[{"note":"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.","wrong":"import { Config } from 'size-limit'","symbol":"Config","correct":"import { type Config } from 'size-limit'"},{"note":"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.","symbol":"run","correct":"import { run } from 'size-limit/run'"},{"note":"Used to create custom reporters for programmatic Size Limit runs, allowing for tailored output formats or integration with other reporting systems.","symbol":"createReporter","correct":"import { createReporter } from 'size-limit/create-reporter'"}],"quickstart":{"code":"/* .size-limit.js */\n/** @type {import('size-limit').Config} */\nmodule.exports = [\n  {\n    path: 'dist/main.js',\n    limit: '10 kB',\n    name: 'Main Bundle'\n  },\n  {\n    path: 'dist/*.css',\n    limit: '2 kB',\n    name: 'CSS Stylesheets'\n  },\n  {\n    path: ['dist/vendor.js', 'dist/utils.js'],\n    limit: '5 kB',\n    webpack: false, // For non-webpack bundles\n    gzip: true\n  }\n];\n\n// To run Size Limit after setting up the config:\n// npx size-limit","lang":"javascript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=12.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=12.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Attempting to run Size Limit v12.0.0 or later on an unsupported Node.js environment.","error":"Error: Node.js 18 is not supported. Please upgrade to Node.js 20 or higher."},{"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`.","cause":"Size Limit could not find a configuration file (`.size-limit.js`, `.size-limit.json`, etc.) or it's misconfigured in `package.json`.","error":"Cannot read config. Make sure that size-limit is mentioned in package.json"},{"fix":"Install `jiti` explicitly as a dependency: `npm install jiti` or `yarn add 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.","error":"Error: Cannot find module 'jiti'"}],"ecosystem":"npm","meta_description":null}