CLI tool for Size Limit
size-limit is a performance budget enforcement tool designed to prevent JavaScript bundle bloat by automatically failing CI builds when size limits are exceeded. Unlike passive bundle analyzers, it calculates the real cost to end users—including gzip compression, browser parsing time, and network overhead—then blocks commits that exceed defined thresholds. This proactive approach catches regressions before they reach production.
The tool integrates directly into continuous integration pipelines, running checks on every commit or pull request. Developers define size budgets in configuration files (typically package.json or .size-limit.json), specifying limits for individual entry points or bundles. When a build exceeds these limits, the CI job fails with detailed reports showing exactly how much the bundle grew and where the excess comes from.
With over 542,000 weekly downloads, size-limit has become a standard tool for teams maintaining performance-critical JavaScript applications, particularly in library development and large-scale web apps. It works with multiple bundlers including webpack, Rollup, and esbuild, and supports various presets for different project types—from small libraries to full applications. The tool is especially valuable in monorepos where multiple packages need independent size constraints, and for open-source libraries where bundle size directly impacts adoption rates.
// Install: npm install --save-dev size-limit @size-limit/preset-small-lib
// package.json configuration
{
"name": "my-library",
"scripts": {
"size": "size-limit",
"test": "jest && npm run size"
},
"size-limit": [
{
"name": "Core Library",
"path": "dist/index.js",
"limit": "10 kB",
"gzip": true
},
{
"name": "Full Bundle with React",
"path": "dist/index.js",
"import": "{ Button, Input }",
"limit": "25 kB",
"webpack": true,
"running": false
}
]
}
// .size-limit.js for advanced configuration
module.exports = [
{
name: "ESM Entry Point",
path: "dist/esm/index.js",
limit: "8 kB",
gzip: true,
brotli: true
},
{
name: "Webpack Bundle",
path: "src/index.ts",
limit: "15 kB",
webpack: true,
config: "./webpack.config.js"
}
];
// Run locally: npx size-limit
// CI integration (GitHub Actions):
// - name: Check bundle size
// run: npm run sizeLibrary Authors: Enforce strict size limits on npm packages to ensure they remain lightweight dependencies. A UI component library might set a 15kB limit per component to guarantee fast load times for consuming applications, automatically rejecting PRs that add unnecessary dependencies or bloat.
Monorepo Management: Set different size budgets for each workspace package in a monorepo. A design system might allow 50kB for the core library, 10kB for utility packages, and 100kB for full framework bundles, with size-limit validating each independently on CI.
Pull Request Quality Gates: Integrate with GitHub Actions to add automated size impact comments on PRs. Teams can immediately see "This change adds 3.2kB (12% increase)" before merging, enabling informed decisions about trade-offs between features and performance.
Progressive Web App Optimization: Maintain strict budgets for critical JavaScript bundles that affect Core Web Vitals. An e-commerce site might enforce a 50kB limit on above-the-fold code to ensure fast First Contentful Paint, with size-limit blocking any changes that push beyond this threshold.
Dependency Audit Automation: Catch when dependency updates unexpectedly inflate bundle sizes. If upgrading a date library adds 20kB due to new transitive dependencies, size-limit fails the build immediately rather than discovering the regression weeks later in production metrics.
npm install size-limitpnpm add size-limitbun add size-limit