<img src="https://ai.github.io/size-limit/logo.svg" align="right" alt="Size Limit logo by Anton Lovchikov" width="120" height="178">
Size Limit is a performance budget tool for JavaScript. It checks every commit on CI, calculates the real cost of your JS for end-users and throws an error if the cost exceeds the limit.
With GitHub action Size Limit will post bundle size changes as a comment in pull request discussion.
With --why
, Size Limit can tell you why your library is of this size
and show the real cost of all your internal dependencies.
We are using Statoscope for this analysis.
file
, webpack
, time
)
and 3 plugin presets for popular use cases (app
, big-lib
, small-lib
).
A CLI tool finds plugins in package.json
and loads the config.webpack
plugin, Size Limit will bundle your JS files into
a single file. It is important to track dependencies and webpack polyfills.
It is also useful for small libraries with many small files and without
a bundler.webpack
plugin creates an empty webpack project, adds your library
and looks for the bundle size difference.time
plugin compares the current machine performance with that of
a low-priced Android devices to calculate the CPU throttling rate.time
plugin runs headless Chrome (or desktop Chrome if it’s
available) to track the time a browser takes to compile and execute your JS.
Note that these measurements depend on available resources and might
be unstable. See here
for more details.Suitable for applications that have their own bundler and send the JS bundle directly to a client (without publishing it to npm). Think of a user-facing app or website, like an email client, a CRM, a landing page or a blog with interactive elements, using React/Vue/Svelte lib or vanilla JS.
File size limit (in kB) is not the best way to describe your JS application cost for developers. Developers will compare the size of the JS bundle with the size of images. But browsers need much more time to parse 100 kB of JS than 100 kB of an image since JS compilers are very complex.
This is why Size Limit support time-based limit. It runs headless Chrome to track the time a browser takes to compile and execute your JS.
JS libraries > 10 kB in size.
This preset includes headless Chrome, and will measure your lib’s execution time. You likely don’t need this overhead for a small 2 kB lib, but for larger ones the execution time is a more accurate and understandable metric that the size in bytes. Libraries like React are good examples for this preset.
JS libraries < 10 kB in size.
This preset will only measure the size, without the execution time, so it’s suitable for small libraries. If your library is larger, you likely want the Big Libraries preset above. Nano ID or Storeon are good examples for this preset.
Size Limit has a GitHub action that comments and rejects pull requests based on Size Limit output.
.github/workflows/size-limit.yml
name: "size"
on:
pull_request:
branches:
- master
jobs:
size:
runs-on: ubuntu-latest
env:
CI_JOB_NUMBER: 1
steps:
- uses: actions/checkout@v1
- uses: andresz1/size-limit-action@v1
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
Plugins or plugin presets will be loaded automatically from package.json
.
For example, if you want to use @size-limit/webpack
, you can just use
npm install --save-dev @size-limit/webpack
, or you can use our preset
@size-limit/preset-big-lib
.
Plugins:
@size-limit/file
checks the size of files with Brotli (default), Gzip
or without compression.@size-limit/webpack
adds your library to empty webpack project
and prepares bundle file for file
plugin.@size-limit/webpack-why
adds reports for webpack
plugin
about your library is of this size to show the cost of all your
dependencies.@size-limit/webpack-css
adds css support for webpack
plugin.@size-limit/esbuild
is like webpack
plugin, but uses esbuild
to be faster and use less space in node_modules
.@size-limit/esbuild-why
add reports for esbuild
plugin
about your library is of this size to show the cost of all your
dependencies.@size-limit/time
uses headless Chrome to track time to execute JS.Plugin presets:
@size-limit/preset-app
contains file
and time
plugins.@size-limit/preset-big-lib
contains webpack
, file
, and time
plugins.@size-limit/preset-small-lib
contains esbuild
and file
plugins.Third-party plugins and presets named starting with size-limit-
are also supported.
For example:
size-limit-node-esbuild
is like @size-limit/esbuild
but for Node libraries.size-limit-preset-node-lib
is like @size-limit/preset-small-lib
but for Node libraries which contains
above node-esbuild
and core file
plugins.nx-size-limit
is an NX build system community plugin.Size Limits supports three ways to define limits config.
size-limit
section in package.json
:
"size-limit": [
{
"path": "index.js",
"import": "{ createStore }",
"limit": "500 ms"
}
]
or a separate .size-limit.json
config file:
[
{
"path": "index.js",
"import": "{ createStore }",
"limit": "500 ms"
}
]
or a more flexible .size-limit.js
or .size-limit.cjs
config file:
module.exports = [
{
path: "index.js",
import: "{ createStore }",
limit: "500 ms"
}
]
or types .size-limit.ts
:
import type { SizeLimitConfig } from '../../packages/size-limit'
module.exports = [
{
path: "index.js",
import: "{ createStore }",
limit: "500 ms"
}
] satisfies SizeLimitConfig
Each section in the config can have these options:
"index.js"
, a pattern "dist/app-*.js"
or an array ["index.js", "dist/app-*.js", "!dist/app-exclude.js"]
."{ lib }"
to test import { lib } from 'lib'
, *
to test all exports,
or { "a.js": "{ a }", "b.js": "{ b }" }
to test multiple files.path
option. It should be
a string with a number and unit, separated by a space.
Format: 100 B
, 10 kB
, 500 ms
, 1 s
.false
it will disable webpack.false
it will disable calculating running time.true
it will use Gzip compression and disable
Brotli compression.false
it will disable any compression.stats.json
from another build to compare
(when --why
is using).If you use Size Limit to track the size of CSS files, make sure to set
webpack: false
. Otherwise, you will get wrong numbers, because webpack
inserts style-loader
runtime (≈2 kB) into the bundle.
--why
You can run size-limit --why
to analyze the bundle.
You will need to install @size-limit/esbuild-why
or @size-limit/webpack-why
depends on which bundler you are using (default is esbuild
).
For @size-limit/esbuild-why
,
it will generate a esbuild-why.html
at the current directory & open it in the browser.
If you also specify --save-bundle <DIR>
,
the report will be generated inside <DIR>
.
If you have multiple sections in your config,
the files will be named esbuild-why-{n}.html
,
or you can give it a custom name:
[
{
"name": "cjs",
/* snap */
},
{
"name": "esm",
/* snap */
}
]
This will produce esbuild-why-cjs.html
and esbuild-why-esm.html
respectively.
For @size-limit/webpack-why
,
it will generate the report and open it in the browser automatically.
const sizeLimit = require('size-limit')
const filePlugin = require('@size-limit/file')
const webpackPlugin = require('@size-limit/webpack')
sizeLimit([filePlugin, webpackPlugin], [filePath]).then(result => {
result //=> { size: 12480 }
})