Size Limit

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.

• Size Limit calculates the time it would take a browser
  to download and execute your JS. Time is a much more accurate
  and understandable metric compared to the size in bytes.
• Size Limit calculations include all dependencies and polyfills
  used in your JS.
• Add Size Limit to Travis CI, Circle CI, or another CI system
  to know if a pull request adds a massive dependency.
• Size Limit is modular to fit different use cases, like big JS applications
  that use their own bundler or small npm libraries with many files.

With --why, Size Limit can tell you why your library is of this size
and show the real cost of all your internal dependencies.

Who Uses Size Limit

• MobX
• Material-UI
• Autoprefixer
• PostCSS reduced
  25% of the size.
• Browserslist reduced
  25% of the size.
• EmojiMart reduced
  20% of the size
• nanoid reduced
  33% of the size.
• React Focus Lock reduced
  32% of the size.
• Logux reduced
  90% of the size.

How It Works

1. Size Limit contains a CLI tool, 3 plugins (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.
2. If you use the 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.
3. The webpack plugin creates an empty webpack project, adds your library
   and looks for the bundle size difference.
4. The time plugin compares the current machine performance with that of
   a low-priced Android devices to calculate the CPU throttling rate.
5. Then the 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.

Usage

JS Applications

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.

1. Install the preset:

   $ npm install --save-dev size-limit @size-limit/preset-app
   

2. Add the size-limit section and the size script to your package.json:

   + "size-limit": [
   +   {
   +     "path": "dist/app-*.js"
   +   }
   + ],
     "scripts": {
       "build": "webpack ./webpack.config.js",
   +   "size": "npm run build && size-limit",
       "test": "jest && eslint ."
     }
   

3. Here’s how you can get the size for your current project:

   $ npm run size
   
     Package size: 30.08 KB with all dependencies, minified and gzipped
     Loading time: 602 ms   on slow 3G
     Running time: 214 ms   on Snapdragon 410
     Total time:   815 ms
   

4. Now, let’s set the limit. Add 25% to the current total time and use that as
   the limit in your package.json:

     "size-limit": [
       {
   +     "limit": "1 s",
         "path": "dist/app-*.js"
       }
     ],
   

5. Add the size script to your test suite:

     "scripts": {
       "build": "webpack ./webpack.config.js",
       "size": "npm run build && size-limit",
   -   "test": "jest && eslint ."
   +   "test": "jest && eslint . && npm run size"
     }
   

6. If you don’t have a continuous integration service running, don’t forget
   to add one — start with Travis CI.

Big Libraries

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. Library like React is a good example for this preset.

1. Install preset:

   $ npm install --save-dev size-limit @size-limit/preset-big-lib
   

2. Add the size-limit section and the size script to your package.json:

   + "size-limit": [
   +   {
   +     "path": "dist/react.production-*.js"
   +   }
   + ],
     "scripts": {
       "build": "webpack ./scripts/rollup/build.js",
   +   "size": "npm run build && size-limit",
       "test": "jest && eslint ."
     }
   

3. Here’s how you can get the size for your current project:

   $ npm run size
   
     Package size: 30.08 KB with all dependencies, minified and gzipped
     Loading time: 602 ms   on slow 3G
     Running time: 214 ms   on Snapdragon 410
     Total time:   815 ms
   

4. Now, let’s set the limit. Add 25% to the current total time and use that
   as the limit in your package.json:

     "size-limit": [
       {
   +     "limit": "1 s",
         "path": "dist/react.production-*.js"
       }
     ],
   

5. Add a size script to your test suite:

     "scripts": {
       "build": "rollup ./scripts/rollup/build.js",
       "size": "npm run build && size-limit",
   -   "test": "jest && eslint ."
   +   "test": "jest && eslint . && npm run size"
     }
   

6. If you don’t have a continuous integration service running, don’t forget
   to add one — start with Travis CI.

7. Add the library size to docs, it will help users to choose your project:

     # Project Name
   
     Short project description
   
     * **Fast.** 10% faster than competitor.
   + * **Small.** 15 KB (minified and gzipped).
   +   [Size Limit](https://github.com/ai/size-limit) controls the size.
   

Small Libraries

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.

1. First, install size-limit:

   $ npm install --save-dev size-limit @size-limit/preset-small-lib
   

2. Add the size-limit section and the size script to your package.json:

   + "size-limit": [
   +   {
   +     "path": "index.js"
   +   }
   + ],
     "scripts": {
   +   "size": "size-limit",
       "test": "jest && eslint ."
     }
   

3. Here’s how you can get the size for your current project:

   $ npm run size
   
     Package size: 177 B with all dependencies, minified and gzipped
   

4. If your project size starts to look bloated, run --why for analysis:

   $ npm run size -- --why
   

5. Now, let’s set the limit. Determine the current size of your library,
   add just a little bit (a kilobyte, maybe) and use that as the limit
   in your package.json:

    "size-limit": [
       {
   +     "limit": "9 KB",
         "path": "index.js"
       }
    ],
   

6. Add the size script to your test suite:

     "scripts": {
       "size": "size-limit",
   -   "test": "jest && eslint ."
   +   "test": "jest && eslint . && npm run size"
     }
   

7. If you don’t have a continuous integration service running, don’t forget
   to add one — start with Travis CI.

8. Add the library size to docs, it will help users to choose your project:

     # Project Name
   
     Short project description
   
     * **Fast.** 10% faster than competitor.
   + * **Small.** 500 bytes (minified and gzipped). No dependencies.
   +   [Size Limit](https://github.com/ai/size-limit) controls the size.
   

Config

Size Limits supports three ways to define config.

1. size-limit section in package.json:

     "size-limit": [
       {
         "path": "index.js",
         "limit": "500 ms"
       }
     ]
   

2. or a separate .size-limit.json config file:

   [
     {
       "path": "index.js",
       "limit": "500 ms"
     }
   ]
   

3. or a more flexible .size-limit.js config file:

   module.exports = [
     {
       path: "index.js",
       limit: "500 ms"
     }
   ]
   

Each section in the config can have these options:

• path: relative paths to files. The only mandatory option.
  It could be a path "index.js", a pattern "dist/app-*.js"
  or an array ["index.js", "dist/app-*.js", "!dist/app-exclude.js"].
• entry: when using a custom webpack config, a webpack entry could be given.
  It could be a string or an array of strings.
  By default, the total size of all entry points will be checked.
• limit: size or time limit for files from the 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.
• name: the name of the current section. It will only be useful
  if you have multiple sections.
• webpack: with false it will disable webpack.
• running: with false it will disable calculating running time.
• gzip: with false it will disable gzip compression.
• brotli: with true it will use brotli compression and disable gzip compression.
• config: a path to a custom webpack config.
• ignore: an array of files and dependencies to exclude from
  the project size calculation.

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.

JS API

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 }
})