### CHANGELOG # Change Log This project adheres to [Semantic Versioning](http://semver.org/). ## 13.0.3 - Removed `picocolors` dependencies. ## 13.0.2 - Fixed glob pattern regression. ## 13.0.1 - Fixed publishing process. ## 13.0.0 - Removed Node.js 20 support. - Removed `tinyglobby` and `jiti` dependencies. - Added npm provenance. ## 12.1.0 - Added `disablePlugins` option (by @JPeer264). - Updated `esbuild`. ## 12.0.1 - Updated `css-minimizer-webpack-plugin` (by @SevereCloud). ## 12.0.0 - Moved `jiti` to optional dependency. - Removed `chokidar` dependency in favor of `fs.watch`. - Removed Node.js 18 support. - Updated `open` & `esbuild` dependencies. - Fixed docs (by @nlopin & @just-boris). ## 11.2.0 - Added `--config` argument (by @EvgenyWas). - Added top-level `await` support to config (by @aryaemami59). - Added `time` option to config (by @EvgenyWas). - Added `message` option to config (by @dartess). - Updated `esbuild`. ## 11.1.6 - Updated `chokidar`. - Updated `esbuild`. - Updated `jiti`. ## 11.1.5 - Reduced dependencies (by @ziebam). - Updated `esbuild`. ## 11.1.4 - Fixed types (by @aryaemami59). ## 11.1.3 - Updated `esbuild`. - Updated CSS loaders for webpack. ## 11.1.2 - Fixed CSS support in esbuild plugin (by @just-boris). ## 11.1.1 - Fixed Windows support (by @aryaemami59). ## 11.1.0 - Added TypeScript support for config (by @aryaemami59). - Fixed `webpack-why` regression (by @hoo00nn). ## 11.0.3 - Fixed `.mjs` config support (by Arya Emami). - Updated `esbuild`. ## 11.0.2 - Fixed `require is not defined` regression. - Updated `esbuild-visualizer`. ## 11.0.1 - Updated `estimo`. - Updated `lilconfig`. ## 11.0 - Moved to Brotli as default compression. Use `gzip: true` for old behavior. ## 10.0.3 - Fixed third-party plugins support (by @JounQin). - Fixed Windows support (by @JounQin). ## 10.0.2 - Fixed `require is not defined` in `webpack-css` (by Andrey Medvedev). - Fixed webpack config defined as function support (by @lev875). ## 10.0.1 - Fixed imports and exports between packages. ## 10.0 - Removed `@size-limit/dual-publish` plugin. - Moved projects to ESM (by @lev875). Size Limit still can be used as CLI in CJS projects. - Updated `globby` dependency. ## 9.0 - Remove Node.js 14 and 16 support. - Moved to React from CDN for `time` plugin (by Aakansha Doshi). ## 8.2.6 - Fixed npm release process. ## 8.2.5 - Fixed opening report in `@size-limit/esbuild-why` (by Yaroslav Chapelskyi). - Updated `esbuild`. ## 8.2.4 - Fixed `@size-limit/esbuild-why` for multiple checks (by Homa Wong). ## 8.2.3 - Fixed npm release process. ## 8.2.2 - Fixed npm release process. ## 8.2.1 - Fixed `@size-limit/esbuild-why` package size. ## 8.2 - Added `@size-limit/esbuild-why` plugin (by Homa Wong). - Fixed peer dependency (by Sébastien Vanvelthem). ## 8.1.2 - Fixed silent mode (by Igor Suvorov). - Updated `esbuild`. - Reduced dependencies. ## 8.1.1 - Updated `esbuild`. ## 8.1 - Added `"*"` value support to `import` (by @denkristoffer). ## 8.0.1 - Fixed `config` and `modifyEsbuildConfig` options (by Angelo Ashmore). - Updated `esbuild`. ## 8.0 - Removed Node.js 12 support. - Added support for third-party plugins support (by @JounQin). - Added field with limit to JSON output (by Elliot Westlake). ## 7.0.8 - Fixed peer dependencies. ## 7.0.7 - Fixed plugin versions in presets. ## 7.0.6 - Added `brotlied` note to CLI output (by @azat-io). - Updated `nanospinner`. ## 7.0.5 - Added `pnpm` examples to migration guide. - Fixed docs (by @azat-io). ## 7.0.4 - Updated `esbuild`. - Updated `nanospinner`. ## 7.0.3 - Fixed package size. ## 7.0.2 - Fixed peer dependency ignore in `@size-limit/esbuild`. ## 7.0.1 - Fixed `--save-bundle` arguments with `@size-limit/esbuild`. - Fixed `ignore` option with `@size-limit/esbuild`. - Fixed `brotli` option without webpack. - Fixed error messages. ## 7.0 - Added `@size-limit/esbuild` plugin for better performance (by Artem Tumin). - Moved `@size-limit/preset-small-lib` to `@size-limit/esbuild`. - Moved CSS from webpack plugin to `@size-limit/webpack-css` (by Egor Ogarkov). - Moved `--why` to `@size-limit/webpack-why` (by Egor Ogarkov). ## 6.0.4 - Updated dependencies. ## 6.0.3 - Updated `nanospinner`. ## 6.0.2 - Fixed Statoscope report location (by Sergey Melyukov). ## 6.0.1 - Replaced `mico-spinner` to `nanospinner`. ## 6.0 - Moved to webpack 5 (by Ludovico Fischer). - Moved from Webpack Bundle Analyzer to Statoscope (by Sergey Melyukov). ## 5.0.5 - Replaced `nanocolors` dependency with `picocolors`. ## 5.0.4 - Replaced `colorette` dependency with `nanocolors`. ## 5.0.3 - Fixed `pnpm` support (by @Tomyail). ## 5.0.2 - Fixed error message on no input files for webpack. - Fixed plugins loading from optional dependencies (by Edouard Menayde). ## 5.0.1 - Fixed `mico-spinner` dependency range. ## 5.0 - Removed Node.js 10 support. - Reduced dependencies (by Stsefanovich Kanstantsin & @enemycnt). ## 4.12.0 - Added `.size-limit.cjs` config file support (by Cole Ellison). ## 4.11.0 - Added `modifyWebpackConfig` option (by Lenz Weber). ## 4.10.3 - Updated `optimize-css-assets-webpack-plugin`. ## 4.10.2 - Use `1000` factor for `KB` and `1024` for `KiB` (by Matthias Kunnen). ## 4.10.1 - Fixed output on missed file (by Viktor Pasynok). ## 4.10 - Added `--silent` argument (by Viktor Pasynok). ## 4.9.2 - Fixed plugin loading for mono repository (by John Grishin). ## 4.9.1 - Reduced dependencies by replacing `cosmiconfig` to `lilconfig`. ## 4.9 - Added auto `--highlight-less` for checks with bytes in limit. - Updated `dual-publish`. ## 4.8 - Added webpack stats support in `--save-bundle` (by Leonard Kinday). ## 4.7 - Added `--highlight-less` argument (by Victor Didenko). ## 4.6.2 - Fixed `peerDependencies` resolving in `import`. - Fixed Node.js 15 support. ## 4.6.1 - Fixed `peerDependencies` support in `import`. - Fixed npm 7 support. - Updated `css-loader` and `file-loader`. ## 4.6 - Added `--hide-passed` argument (by Kristján Oddsson). ## 4.5.7 - Do not show loader in JSON mode (by Billy Vong). ## 4.5.6 - Fix “file was not found” behaviour (by Pavel Pustovalov). ## 4.5.5 - Dropped Node.js 13.0-13.6 support because of ES modules bug in that versions. ## 4.5.4 - Better warning on missed value in CLI argument (by Mikhail Vyrodov). ## 4.5.3 - Fixed `MaxListenersExceededWarning` (by Pavel Pustovalov). - Fixed `gzipped` note (by Evgeniy Timokhov). ## 4.5.2 - Replace color output library. ## 4.5.1 - Reduce dependencies. - Improve docs (by Mikhail Bashurov). ## 4.5 - Add `--clean-dir` argument. ## 4.4.5 - Fix Windows support. ## 4.4.4 - Fix Yarn 2 support. ## 4.4.3 - Fix Windows support (by Anton Khlynovskiy). ## 4.4.2 - Update `nanoid`. ## 4.4.1 - Update `file-loader`. - Add peer dependency to `dual-publish` plugin. ## 4.4 - Add `--watch` support (by @jayhoney). ## 4.3.1 - Fix `import` option. ## 4.3 - Add multiple files support for `import` option. - Add multiple files support for `import` option. ## 4.2.1 - Fix `dual-publish` error. ## 4.2 - Add `@size-limit/dual-publish` plugin. ## 4.1.1 - Fix `import` option. ## 4.1 - Add tree-shaking support with `import` option (by Brian Schlenker). ## 4.0.2 - Fix `gzip` option plugins test. - Update `ci-job-number`. ## 4.0.1 - Fix note text (by Pavel Pustovalov). ## 4.0 - Move `size-limit` from `dependencies` to `peerDependencies`. ## 3.0.1 - Add Yarn PnP and Yarn 2 support (by Pavel Pustovalov). ## 3.0 - Drop Node.js 8 support. - Add Brotli support (by Viktor Pasynok). ## 2.2.4 - Improve `MaxListenersExceededWarning` fix (by Pavel Pustovalov). ## 2.2.3 - Fix `MaxListenersExceededWarning` (by Pavel Pustovalov). ## 2.2.2 - Fix JS API. ## 2.2.1 - Fix warning message (by Alexey Taktarov). ## 2.2 - Add JS API. ## 2.1.6 - Fix `--why` for entries with exceeded limit. - Fix `--why` for multiple entries. ## 2.1.5 - Fix running time calculation on parallel tasks. - Fix CI warning text during Puppeteer error. ## 2.1.4 - Add warning for `size-limit` in dependencies. ## 2.1.3 - Fix plugin loading (by Alexandr Antonov). ## 2.1.2 - Update dependencies. ## 2.1.1 - Ignore non `.js` or `.mjs` files in running time. - Speed up running time calculation. ## 2.1 - Add `--debug` argument. ## 2.0.2 - Fix time limit support. ## 2.0.1 - Fix possible webpack temporal directory name conflict. ## 2.0 - Rewrite tool with modular architecture. Migration: 1. Update `size-limit` to 2.x version. 2. Run `npx size-limit`. 3. Console will output instructions for installing necessary preset. ## 1.3.8 - Do not download Chrome for Puppeteer if you already have desktop Chrome. ## 1.3.7 - More accurate `--why` (by Anton Korzunov). - Fix `ignore` and `peerDependencies` (by Anton Korzunov). - Fix `--no-gzip` argument. ## 1.3.6 - Fix `package.json`-less project support. - Improve error message on wrong `getSize()` call. - Fix JSDoc. ## 1.3.5 - Fix CI warning text. ## 1.3.4 - Fix CI warning style. ## 1.3.3 - Fix ignoring scoped packages. ## 1.3.2 - Fix support extension-less `package.main` (by Homa Wong). - Add warning or Circle CI. ## 1.3.1 - Speed up running time calculation. ## 1.3 - Add `--save-bundle` argument (by Ivan Solovev). ## 1.2 - Add `--json` argument (by Pavel Vostrikov). ## 1.1.2 - Fix running time calculation on `webpack: false`. ## 1.1.1 - Allow to use Size Limit on CI with Node.js <8 tasks. ## 1.1 - Calculate time to download and execute JS. - Improve CLI UI. ## 1.0.1 - Fix Markdown files support (by Scaria Rex Arun and Kiryl Misachenka). ## 1.0 - Add `.size-limit.json` config name support. ## 0.22 - Drop Node.js 6 support. - Update inner CLI tools. ## 0.21.1 - Use `css-loader` 2.0 (by Redmond Tran). - Use `file-loader` 3.0. ## 0.21 - Add support for dynamic filename in custom Webpack config (by Naijia Liu). - Add `entry` option (by Naijia Liu). ## 0.20.1 - Use `compression-webpack-plugin` 2.0. - Use `webpack-bundle-analyzer` 3.0. ## 0.20 - Use `package.json#main` as default path for limit. - Fix custom webpack config support with `resolve` or `resolveLoader` options. ## 0.19.3 - Update `file-loader` and `style-loader`. ## 0.19.2 - Fix `ignore` option (by Jayden Seric). ## 0.19.1 - Use `style-loader` 0.22. ## 0.19 - Add `ignore` option to config. ## 0.18.5 - Fix absolute path support. ## 0.18.4 - Update dependencies. - Fix documentation. ## 0.18.3 - Use `read-pkg-up` 4.x. - Remove development config from `package.json`. ## 0.18.2 - Fix size with new webpack. ## 0.18.1 - Move development config files from npm package. ## 0.18 - Add `.size-limit.js` config support (by Olivier Tassinari). ## 0.17.1 - Use `cosmiconfig` 5.x. - Improve CI (by Daniel Ruf). ## 0.17 - Remove deprecated limit CLI API and add `--limit` argument. ## 0.16.2 - Fix `peerDependencies` and `--why` (by Bogdan Chadkin). ## 0.16.1 - Allow to use Size Limit in CI with Node.js 4. ## 0.16 - `getSize()` now returns `{ gzip, parsed }` (by Bogdan Chadkin). - Improve size calculation accuracy (by Bogdan Chadkin). - Array support in the `path` (by Bogdan Chadkin). ## 0.15.2 - Improve performance (by Bogdan Chadkin). ## 0.15.1 - Allow to use Size Limit in CI with Node.js 4. ## 0.15 - Remove Node.js 4 support. - Use `webpack` 4.0 (by Jayden Seric). - Use `globby` 8.0. ## 0.14.1 - Use `cosmiconfig` 4.0. - Use `yargs` 11.0. ## 0.14 - Add `name` option to config. - Add `gzip` option to config. ## 0.13.2 - Use `globby` 7.0. ## 0.13.1 - Allow to use Size Limit without `package.json`. ## 0.13 - Add `.size-limit` config support (by Vladimir Borovik). ## 0.12.1 - Fix dependency resolving with custom webpack config (by Sivan Mehta). ## 0.12 - Add custom webpack config support (by Sivan Mehta). ## 0.11.6 - Fix CLI messages (by @mute). ## 0.11.5 - Better error message on `--why` with `"webpack": false`. ## 0.11.4 - Update `yargs`. ## 0.11.3 - Better error message on wrong config. - Fix English in config error messages (by Tim Marinin). ## 0.11.2 - Show config example in config error messages. - Better error message on wrong config. ## 0.11.1 - Better error message on missed file in legacy CLI. ## 0.11 - Ignore size of `peerDependencies`. ## 0.10 - Add CSS files support (by Sebastian Werner). - Add support for more static files types (by Sebastian Werner). ## 0.9 - Use UglifyJS 3 to support ES2016 out of box. - Add argument and option to disable webpack. - Deprecate argument and option for Babili. - Deprecate limit in CLI arguments. - Deprecate old `"sizeLimit"` section name. - Better error messages style. - Clean npm package from test files. ## 0.8.4 - Fix error messages text (by Alexandr Subbotin). ## 0.8.3 - Improve error messages style. ## 0.8.2 - Better output for projects with multiple limits. - Fix multiple limits support in `--why`. ## 0.8.1 - Improve CLI help (by Peter deHaan). ## 0.8 - Add `size-limit` configuration section support. ## 0.7.1 - Fix multiline error messages in CLI. - Do not load `node-zopfli` as loose dependency. ## 0.7 - Add glob pattern support to `sizeLimit` section. ## 0.6.2 - Better project name in Webpack Bundle Analyzer. ## 0.6.1 - Load images by `file-loader`. ## 0.6 - Add `sizeLimit` configuration section support. ## 0.5.1 - Use gzip sizes in Webpack Bundle Analyzer. ## 0.5 - Add Semaphore support. ## 0.4 - Add CircleCI support. ## 0.3.2 - Fix bundle name in `--why` mode. - Move gzip calculation inside webpack. ## 0.3.1 - Use `read-pkg-up` to find `package.json`. - Use `ci-job-number` to detect CI job number. ## 0.3 - Run only on first CI job to save CI resources. ## 0.2 - Add `--babili` argument. - Use Chalk 2. ## 0.1.3 - Fix CLI text (by Yaroslav Markin). ## 0.1.2 - Fix CLI text (by Marais Rossouw). ## 0.1.1 - Fix parsing `B` unit without kilo/mega prefix. ## 0.1 - Initial release. --- ### README # Size Limit Size Limit logo by Anton Lovchikov 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. - **ES modules** and **tree-shaking** support. - Add Size Limit to **GitHub Actions**, **Circle CI** or another CI system to know if a pull request adds a massive dependency. - **Modular** to fit different use cases: big JS applications that use their own bundler or small npm libraries with many files. - Can calculate **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. Additionally, you can [customize time plugin] via config for every check with network speed, latency and so on. - Calculations include **all dependencies and polyfills** used in your JS.

Size Limit CLI

With **[GitHub action]** Size Limit will post bundle size changes as a comment in pull request discussion.

Size Limit comment in pull request about bundle size changes

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.

Statoscope example

---   Size Limit is built by Evil Martians, an American design and engineering consultancy for developer tools, AI, and cybersecurity startups. --- [GitHub action]: https://github.com/andresz1/size-limit-action [Statoscope]: https://github.com/statoscope/statoscope [customize time plugin]: https://github.com/ai/size-limit/packages/time#customize-network-speed ## Who Uses Size Limit - [MobX](https://github.com/mobxjs/mobx) - [Material-UI](https://github.com/callemall/material-ui) - [Ant Design](https://github.com/ant-design/ant-design/) - [Autoprefixer](https://github.com/postcss/autoprefixer) - [PostCSS](https://github.com/postcss/postcss) reduced [25% of the size](https://github.com/postcss/postcss/commit/150edaa42f6d7ede73d8c72be9909f0a0f87a70f). - [Browserslist](https://github.com/browserslist/browserslist) reduced [25% of the size](https://github.com/browserslist/browserslist/commit/640b62fa83a20897cae75298a9f2715642531623). - [EmojiMart](https://github.com/missive/emoji-mart) reduced [20% of the size](https://github.com/missive/emoji-mart/pull/111) - [nanoid](https://github.com/ai/nanoid) reduced [33% of the size](https://github.com/ai/nanoid/commit/036612e7d6cc5760313a8850a2751a5e95184eab). - [React Focus Lock](https://github.com/theKashey/react-focus-lock) reduced [32% of the size](https://github.com/theKashey/react-focus-lock/pull/48). - [Logux](https://github.com/logux) reduced [90% of the size](https://github.com/logux/logux-client/commit/62b258e20e1818b23ae39b9c4cd49e2495781e91). ## 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. Note that these measurements depend on available resources and might be unstable. [See here](https://github.com/mbalabash/estimo/issues/5) for more details. ## 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.
Show instructions 1. Install the preset: ```sh npm install --save-dev size-limit @size-limit/file ``` 2. Add the `size-limit` section and the `size` script to your `package.json`: ```diff + "size-limit": [ + { + "path": "dist/app-*.js" + } + ], "scripts": { "build": "webpack ./webpack.config.js", + "size": "npm run build && size-limit", "test": "vitest && eslint ." } ``` 3. Here’s how you can get the size for your current project: ```sh $ npm run size Package size: 30.08 kB with all dependencies, minified and brotlied ``` 4. Now, let’s set the limit. Add 25% to the current total size and use that as the limit in your `package.json`: ```diff "size-limit": [ { + "limit": "35 kB", "path": "dist/app-*.js" } ], ``` 5. Add the `size` script to your test suite: ```diff "scripts": { "build": "webpack ./webpack.config.js", "size": "npm run build && size-limit", - "test": "vitest && eslint ." + "test": "vitest && eslint . && npm run size" } ``` 6. If you don’t have a continuous integration service running, don’t forget to add one — start with GitHub Actions.
### JS Application and Time-based Limit 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.
Show instructions 1. Install the preset: ```sh npm install --save-dev size-limit @size-limit/preset-app ``` 2. Add the `size-limit` section and the `size` script to your `package.json`: ```diff + "size-limit": [ + { + "path": "dist/app-*.js" + } + ], "scripts": { "build": "webpack ./webpack.config.js", + "size": "npm run build && size-limit", "test": "vitest && eslint ." } ``` 3. Here’s how you can get the size for your current project: ```sh $ npm run size Package size: 30.08 kB with all dependencies, minified and brotlied 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`: ```diff "size-limit": [ { + "limit": "1 s", "path": "dist/app-*.js" } ], ``` 5. Add the `size` script to your test suite: ```diff "scripts": { "build": "webpack ./webpack.config.js", "size": "npm run build && size-limit", - "test": "vitest && eslint ." + "test": "vitest && eslint . && npm run size" } ``` 6. If you don’t have a continuous integration service running, don’t forget to add one — start with GitHub Actions.
### 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. Libraries like [React] are good examples for this preset.
Show instructions 1. Install preset: ```sh 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`: ```diff + "size-limit": [ + { + "path": "dist/react.production-*.js" + } + ], "scripts": { "build": "webpack ./scripts/rollup/build.js", + "size": "npm run build && size-limit", "test": "vitest && eslint ." } ``` 3. If you use ES modules you can test the size after tree-shaking with `import` option: ```diff "size-limit": [ { "path": "dist/react.production-*.js", + "import": "{ createComponent }" } ], ``` 4. Here’s how you can get the size for your current project: ```sh $ npm run size Package size: 30.08 kB with all dependencies, minified and brotlied Loading time: 602 ms on slow 3G Running time: 214 ms on Snapdragon 410 Total time: 815 ms ``` 5. Now, let’s set the limit. Add 25% to the current total time and use that as the limit in your `package.json`: ```diff "size-limit": [ { + "limit": "1 s", "path": "dist/react.production-*.js" } ], ``` 6. Add a `size` script to your test suite: ```diff "scripts": { "build": "rollup ./scripts/rollup/build.js", "size": "npm run build && size-limit", - "test": "vitest && eslint ." + "test": "vitest && eslint . && npm run size" } ``` 7. If you don’t have a continuous integration service running, don’t forget to add one — start with GitHub Actions. 8. Add the library size to docs, it will help users to choose your project: ```diff # Project Name Short project description * **Fast.** 10% faster than competitor. + * **Small.** 15 kB (minified and brotlied). + [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.
Show instructions 1. First, install `size-limit`: ```sh 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`: ```diff + "size-limit": [ + { + "path": "index.js" + } + ], "scripts": { + "size": "size-limit", "test": "vitest && eslint ." } ``` 3. Here’s how you can get the size for your current project: ```sh $ npm run size Package size: 177 B with all dependencies, minified and brotlied ``` 4. If your project size starts to look bloated, run `--why` for analysis: ```sh npm run size -- --why ``` > We use [Statoscope](https://github.com/statoscope/statoscope) as bundle analyzer. 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`: ```diff "size-limit": [ { + "limit": "9 kB", "path": "index.js" } ], ``` 6. Add the `size` script to your test suite: ```diff "scripts": { "size": "size-limit", - "test": "vitest && eslint ." + "test": "vitest && eslint . && npm run size" } ``` 7. If you don’t have a continuous integration service running, don’t forget to add one — start with GitHub Actions. 8. Add the library size to docs, it will help users to choose your project: ```diff # Project Name Short project description * **Fast.** 10% faster than competitor. + * **Small.** 500 bytes (minified and brotlied). No dependencies. + [Size Limit](https://github.com/ai/size-limit) controls the size. ```
[Storeon]: https://github.com/ai/storeon/ [Nano ID]: https://github.com/ai/nanoid/ [React]: https://github.com/facebook/react/ ## Reports Size Limit has a [GitHub action] that comments and rejects pull requests based on Size Limit output. 1. Install and configure Size Limit as shown above. 2. Add the following action inside `.github/workflows/size-limit.yml` ```yaml 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 }} ``` ## Config ### Plugins and Presets 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 Third-party plugins and presets named starting with `size-limit-` are also supported. For example: - [`size-limit-node-esbuild`](https://github.com/un-ts/size-limit/tree/main/packages/node-esbuild) is like `@size-limit/esbuild` but for Node libraries. - [`size-limit-preset-node-lib`](https://github.com/un-ts/size-limit/tree/main/packages/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`](https://github.com/LironHazan/nx-size-limit) is an [NX](https://nx.dev/community) build system community plugin. ### Limits Config Size Limits supports three ways to define limits config. 1. `size-limit` section in `package.json`: ```json "size-limit": [ { "path": "index.js", "import": "{ createStore }", "limit": "500 ms" } ] ``` 2. or a separate `.size-limit.json` config file: ```js ;[ { path: 'index.js', import: '{ createStore }', limit: '500 ms' } ] ``` 3. or a more flexible `.size-limit.js` or `.size-limit.cjs` config file: ```js module.exports = [ { path: 'index.js', import: '{ createStore }', limit: '500 ms' } ] ``` 4. or types `.size-limit.ts`: ```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: - **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"]`. - **import**: partial import to test tree-shaking. It could be `"{ lib }"` to test `import { lib } from 'lib'`, `*` to test all exports, or `{ "a.js": "{ a }", "b.js": "{ b }" }` to test multiple files. - **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. - **message**: an optional custom message to display additional information, such as guidance for resolving errors, relevant links, or instructions for next steps when a limit is exceeded. - **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. - **webpack**: with `false` it will disable webpack. - **running**: with `false` it will disable calculating running time. - **gzip**: with `true` it will use Gzip compression and disable Brotli compression. - **brotli**: with `false` it will disable any compression. - **config**: a path to a custom webpack or esbuild config. - **ignore**: an array of files and dependencies to exclude from the project size calculation. - **modifyWebpackConfig**: (.size-limit.js only) function that can be used to do last-minute changes to the webpack config, like adding a plugin. - **modifyEsbuildConfig**: (.size-limit.js only) function that can be used to do last-minute changes to the webpack config, like adding a plugin. - **compareWith**: path to `stats.json` from another build to compare (when `--why` is using). - **uiReports**: custom UI reports list (see [Statoscope docs]). - **disablePlugins**: npm package names of plugins to skip for this check. For example: `"@size-limit/webpack"`, `"@size-limit/esbuild"`, or `"@size-limit/time"`. 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. Also, you avoid having a config and pass the limit to CLI: ```sh npm install --save-dev @size-limit/file npx size-limit --limit "10 kB" dist/bundle.js ``` Additionally, you can specify a custom path to your configuration file when running the CLI: ```sh npx size-limit --config configs/size-limit.json ``` [Statoscope docs]: https://github.com/statoscope/statoscope/tree/master/packages/webpack-plugin#optionsreports-report [pattern]: https://nodejs.org/api/fs.html#fspromisesglobpattern-options ## Analyze with `--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 `, the report will be generated inside ``. 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: ```jsonc [ { "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. ## JS API ```js 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 } }) ``` ---