size-limit

What is size-limit?

Size Limit is a performance monitoring tool for JavaScript projects. It helps you keep your project within a specific size limit by analyzing the size of your JavaScript bundles and providing warnings when the size exceeds the specified limit.

What are size-limit's main functionalities?

Bundle Size Analysis

This feature allows you to specify the path to your JavaScript bundle and set a size limit. Size Limit will analyze the bundle and ensure it does not exceed the specified limit.

module.exports = [
  {
    path: 'dist/bundle.js',
    limit: '500 KB'
  }
];

Custom Configurations

You can customize the analysis by enabling gzip compression or disabling the running of the bundle. This provides more flexibility in how you measure the size of your bundles.

module.exports = [
  {
    path: 'dist/bundle.js',
    limit: '500 KB',
    gzip: true,
    running: false
  }
];

Multiple Bundles

Size Limit supports analyzing multiple bundles in a single configuration. This is useful for projects with multiple entry points or output files.

module.exports = [
  {
    path: 'dist/bundle1.js',
    limit: '300 KB'
  },
  {
    path: 'dist/bundle2.js',
    limit: '200 KB'
  }
];

Other packages similar to size-limit

webpack-bundle-analyzer

Webpack Bundle Analyzer is a tool that visualizes the size of webpack output files with an interactive zoomable treemap. It provides a detailed breakdown of the bundle contents, making it easier to identify large modules and optimize the bundle size. Unlike Size Limit, it focuses more on visualization and detailed analysis rather than enforcing size limits.

bundlesize

Bundlesize is a tool that lets you set size limits for your JavaScript bundles and reports the size of the bundles in your CI/CD pipeline. It is similar to Size Limit in that it enforces size limits, but it integrates more tightly with CI/CD workflows and provides a simpler configuration.

source-map-explorer

Source Map Explorer analyzes JavaScript bundles using source maps to determine which files contribute to the bundle size. It provides a detailed breakdown of the bundle contents, similar to Webpack Bundle Analyzer, but it relies on source maps for its analysis. This makes it useful for understanding the impact of individual source files on the final bundle size.

README

Size Limit

Size Limit is a linter for your JS application or library performance. It calculates the real cost of your JS for end-users and throws an error if the cost exceeds the limit.

• Size Limit calculate the time, which browser need to download and execute your JS. It’s much more accurate and understandable metric compare to size in bytes.
• Size Limit counts the cost including all dependencies and polyfills which is used in your JS.
• You can add Size Limit to Travis CI, Circle CI, etc and set the limit. If you accidentally add a massive dependency, Size Limit will throw an error.

With --why Size Limit can tell you why your library has 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. Applications bundles JS files into the single file. Otherwise, many small JS libraries have many small separated files. For this libraries Size Limit creates an empty webpack project Then, it adds your library as a dependency to the project and calculates the real cost of your libraries, including all dependencies and webpack’s polyfills. Size Limit doesn’t run webpack for application, which already has JS bundle.
2. Size Limit compare current machine performance with low-priced Android devices to calculate CPU throttling rate.
3. To be specific, Size Limit runs headless Chrome with CPU throttling rate. Then it loads your JS code there and tracks the time using by Chrome to compile and execute JS.

Usage for Applications and Big Libraries

This guide is for two use cases:

• Application with bundler (like webpack or Parcel). Any React or Vue.js application is this use case.
• JS libraries, which use webpack or Rollup to build dist/umd/lib.produciton.js-kind file to put it to npm package. React is a good example.

If you have a small JS library with many separated files in npm package, see the next section.

1. First, install size-limit:

   $ npm install --save-dev size-limit
   

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

   + "size-limit": [
   +   {
   +     "webpack": false,
   +     "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% for current total time and use that as a limit in your package.json:

     "size-limit": [
       {
   +     "limit": "1 s",
         "webpack": false,
         "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.

Usage for Small Libraries

This guide is for small JS libraries with many small separated files in their npm package. Nano ID or Storeon could be a good example.

1. First, install size-limit:

   $ npm install --save-dev size-limit
   

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

   + "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
     Loading time: 10 ms on slow 3G
     Running time: 49 ms on Snapdragon 410
     Total time:   59 ms
   

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 a 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.

Config

Size Limits supports three ways to define config.

1. size-limit section to package.json:

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

2. or separated .size-limit.json config file:

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

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

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

Each section in the config could have 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"].
• 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 path option. It should be a string with a number and unit. Format: 100 B, 10 KB, 500 ms, 1 s.
• name: the name of this section. It will be useful only if you have multiple sections.
• webpack: with false will disable webpack.
• running: with false will disable calculating running time.
• gzip: with false will disable gzip compression.
• config: a path to custom webpack config.
• ignore: an array of files and dependencies to ignore from project size.

If you use Size Limit to track the size of CSS files only set webpack: false. Otherwise, you will get wrong numbers, because webpack inserts style-loader runtime (≈2 KB) into the bundle.

API

const getSize = require('size-limit')

const index = path.join(__dirname, 'index.js')
const extra = path.join(__dirname, 'extra.js')

getSize([index, extra]).then(size => {
  // size => { gzip, parsed, running, loading }
  if (size.gzip > 1 * 1024 * 1024) {
    console.error('Project is now larger than 1MB!')
  }
})

Changelog

1.1.2

• Fix running time calculation on webpack: false.