Size Limit — Performance Budget Tool for JavaScript Apps

Introduction

Size Limit is a performance budget tool by Andrey Sitnik (creator of PostCSS and Autoprefixer) that checks every commit for JavaScript bundle size regressions. Unlike simple byte counters, it can measure actual browser execution time on throttled hardware, giving developers a realistic picture of end-user performance impact.

What Size Limit Does

• Calculates the real download and execution cost of JavaScript bundles
• Enforces size budgets in CI and blocks merges that exceed configured limits
• Reports results as GitHub PR comments via the size-limit-action integration
• Supports multiple measurement modes: file size, gzip size, brotli size, and execution time
• Works with any bundler output including webpack, Rollup, esbuild, and Vite

Architecture Overview

Size Limit uses a modular plugin system with presets for different use cases. The core engine reads entry point files, optionally bundles them with esbuild or webpack, applies compression, and measures the result. The time plugin launches headless Chrome with CPU throttling calibrated to low-end Android devices and records script evaluation time. Results are compared against limits defined in package.json or a dedicated config file.

Self-Hosting & Configuration

• Install via npm with a preset matching your project type (small-lib, big-lib, or app)
• Define size limits in package.json under the size-limit key or in .size-limit.json
• Add to CI scripts or use the official GitHub Action for automated PR comments
• Configure CPU throttling factor to match your target user hardware profile
• Integrate with existing webpack or esbuild configs for accurate bundle analysis

Key Features

• Execution time measurement simulates real performance on low-end devices
• Modular preset system adapts to libraries, apps, or framework-specific setups
• GitHub Action posts clear size comparison tables directly on pull requests
• Supports tree-shaking analysis to show what your users actually download
• Zero-config defaults that work for most projects out of the box

Comparison with Similar Tools

• Bundlephobia — online tool for checking npm package sizes; Size Limit runs locally on your actual build output
• webpack-bundle-analyzer — visualizes bundle contents; Size Limit enforces hard limits in CI
• Lighthouse — full page performance audit; Size Limit focuses specifically on JavaScript cost
• Import Cost — VS Code extension showing import sizes inline; Size Limit provides CI-enforced budgets

FAQ

Q: Does Size Limit bundle my code or measure existing output? A: Both. The app preset measures existing build output. The small-lib preset can bundle entry points with esbuild to simulate what users download.

Q: How accurate is the time measurement? A: It uses headless Chrome with CPU throttling calibrated against real low-end Android devices, providing a reproducible approximation of real-world parse and execution time.

Q: Can I use it with monorepos? A: Yes, configure multiple entries in the size-limit array, each with its own path and limit. It works well with Turborepo, Nx, and Lerna setups.

Q: What happens when a limit is exceeded? A: The CLI exits with a non-zero code, failing the CI check. The GitHub Action posts a comment showing which files exceeded their budgets and by how much.

Sources

• https://github.com/ai/size-limit
• https://evilmartians.com/chronicles/size-limit-make-the-web-lighter