bundlesize: a CI gate for JavaScript bundle budgets

What bundlesize actually gates

A JavaScript build produces files whose byte size drifts upward one pull request at a time. Nobody notices until a vendor chunk has doubled. bundlesize turns that drift into a pass or fail signal: you list build files with a maximum size, and the CLI compares each file against its limit. The README describes the project as keeping your bundle size in check, and the package description in package.json says "Keep your library size in check".

The intended user is a library or application maintainer who already has a build step and a CI provider. The README lists bootstrap, lighthouse, styled-components, emotion, Popper.js, redux-saga and others under "who uses bundlesize", but that list is a statement of past adoption, not a quality measure, and it is stale relative to the current release line. What matters for evaluation is narrower: bundlesize reads files that already exist on disk. It does not compile anything, so it fits projects that can produce artifacts before the size check runs.

How the size comparison works

The entry point is index.js, exposed as the bundlesize binary in package.json. Configuration is read through cosmiconfig, which is why the array can live in package.json under the bundlesize key, in bundlesize.config.json, or in a file passed with --config. The README documents the separate-file format as an object with a files array, while the package.json form is the array itself.

Each entry has a path and a maxSize. Paths are resolved with glob, so build/**/main-*.js matches hashed output from create-react-app or Next.js, and the README notes that a pattern matching several files creates a new row for each file. Before comparing, bundlesize compresses the file. The default is gzip, implemented with gzip-size; brotli is available through brotli-size; and compression can be switched off entirely. Sizes are parsed with bytes, so "30 kB" and "3 kB" are the strings you write in config.

The GitHub integration is the part with the most moving pieces. bundlesize can post a check on every pull request, and the README says this currently works with Travis CI, CircleCI, Wercker and Drone. You authorize the bundlesize GitHub app for repo:status scope, copy the token, and store it as BUNDLESIZE_GITHUB_TOKEN in the CI project settings. On other CI systems you supply CI_REPO_OWNER, CI_REPO_NAME, CI_COMMIT_MESSAGE, CI_COMMIT_SHA and CI=true yourself. The README points Jenkins users at ${env.GIT_COMMIT} for the SHA. That is a manual, provider-shaped integration surface, and the TODO section still lists AppVeyor support and automated environment variable setup as unfinished work.

Installing bundlesize and running a first check

The README gives two install paths, npm and yarn. Both put the CLI in devDependencies.

npm install bundlesize --save-dev

yarn add bundlesize --dev

After that, add a script to package.json. The README's example replaces the test script, which is worth thinking about: if your test script already runs a test runner, chain the commands rather than overwriting it.

"scripts": {
  "test": "bundlesize"
}

There is also an npx route for NPM 5.2 and above, documented as `npx bundlesize`. For a first real check, write a config file. The README shows the separate-file form with a files array, which is what the repository's own examples/bundlesize.config.json follows.

{
  "files": [
    {
      "path": "./build/vendor.js",
      "maxSize": "30 kB"
    },
    {
      "path": "./build/chunk-*.js",
      "maxSize": "10 kB"
    }
  ]
}

Run the CLI against that file. If you keep the config somewhere other than the project root, the README documents a --config flag, for example `bundlesize --config configs/bundlesize.json`. Whatever the terminal prints, check one thing before committing the budget: the reported number is the gzipped size by default, so a limit copied from an uncompressed file listing will be wrong. Set the budget from the number bundlesize itself reports, or set compression explicitly.

{
  "files": [
    {
      "path": "./build/vendor.js",
      "maxSize": "5 kB",
      "compression": "brotli"
    }
  ]
}

There is a config-free mode, `bundlesize -f "dist/*.js" -s 20kB`, but the README states it does not recommend that approach and that it might be deprecated in a future version. Treat it as a scratch command, not a build configuration.

Where bundlesize stops being the right tool

bundlesize measures files. It does not build them and it does not explain them. If your entry point has grown because a dependency pulled in a large subtree, bundlesize will report that the output is too big and stop there; the module-level attribution is not part of its job. That is a real boundary, not a defect, but it decides which tool you reach for.

The second limitation is environmental. The pull request check depends on GitHub plus one of four documented CI providers, or on you hand-feeding five environment variables. The README's TODO still lists AppVeyor and automated setup as open items, and the README itself asks users to "Ask me for help if you're stuck" on the custom-CI path. A project on GitLab CI or a self-hosted runner is in the manual branch from the first commit.

The third is maintenance tempo. The repository is not archived, and the last push was on 2026-07-29, so the codebase is not abandoned. But the release history is thin: v0.18.0, the release that allowed the config to live in a different file, dates from 2019, and v0.18.2, described as security patches, dates from 2024-03-15. A tool whose dependency set includes cosmiconfig 5.x, glob 7.x, gzip-size 4.x and commander 2.x is carrying several major versions behind current lines. That is a supply-chain and compatibility consideration you should weigh before adding it to a pipeline you expect to keep for years.

Finally, the budget itself is a judgment call the tool cannot make for you. "30 kB" is a number you chose. bundlesize enforces it consistently, which is the useful part, but it will happily enforce a limit that is too tight and block legitimate work, or too loose and never fire.

size-limit, BuildSize and webpack-bundle-analyzer compared

The README names three similar projects, and the differences are architectural rather than cosmetic.

size-limit, per the README, "Uses webpack, builds your files for you." That is the sharpest contrast. bundlesize is a post-build measurement; size-limit owns the build step. If your project already has a reproducible build artifact in CI, bundlesize's model is simpler, because there is no second bundler configuration to keep in sync. If you would rather not maintain a separate build invocation for the size check, size-limit removes that duplication at the cost of running webpack.

BuildSize is described as a "GitHub App, no manual configuration required". That directly addresses the BUNDLESIZE_GITHUB_TOKEN and five-environment-variable setup described above. The trade-off is control: a hosted app decides how it obtains and measures your files, whereas bundlesize's config is a JSON file in your repository that you can read.

travis-weigh-in is the third, and the README's only note is that it "Uses Python rather than Node.js". For a Node project that already has npm in CI, adding a Python toolchain for one check is friction; for a Python-heavy repository that ships JavaScript assets, the reverse holds.

webpack-bundle-analyzer and the analyzer plugins for Vite and Angular appear in the search phrases around this project, but they answer a different question. An analyzer produces a treemap of what is inside the bundle; bundlesize produces a pass or fail against a number. They are complementary, and using one does not cover the other.

Maintenance, upgrades and the MIT licence

bundlesize is MIT licensed, copyright siddharthkp, per the LICENSE reference in the README and the license field in package.json. MIT is permissive: you can use, modify and redistribute it, including in commercial and closed-source products, provided the copyright notice and permission notice are retained. That is a summary of the licence text, not legal advice; read LICENSE in the repository if the distinction matters to your organization.

The upgrade picture is the practical cost. The package is published on npm, so upgrades arrive as ordinary dependency bumps. The risk sits in the transitive tree. cosmiconfig 5.x, glob 7.x, gzip-size 4.x and commander 2.x are pinned by major version, and the 2024 release is explicitly a security patch, which suggests the project's maintenance activity has concentrated on dependency advisories rather than feature work. Plan for periodic `npm audit` review of the tree rather than expecting the tool to move forward on its own.

There is no documented rollback story in the README for a failed check, and no documented migration guide between config formats. The two config shapes (an array in package.json, an object with a files key in a separate file) both remain valid, so a migration is not forced, but you should pick one and stay with it. The repository also ships bundlesize-init and bundlesize-pipe binaries alongside the main CLI; the README documents neither of them, so if you encounter them in the package, treat their behaviour as undocumented rather than assuming they are supported entry points.

Editorial conclusion

Adopt bundlesize if you already produce build artifacts and want a hard byte ceiling per file, especially on Travis, CircleCI, Wercker or Drone where the GitHub check integration is documented. Do not adopt it if you want the tool to run your bundler or analyze the module graph; size-limit and webpack-bundle-analyzer answer those questions instead. Before wiring it in, run bundlesize once locally against your real build directory and confirm the gzipped number your config produces, because the default compression mode is gzip and a budget set from an uncompressed file size will fail on the first CI run.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. siddharthkp/bundlesize on GitHub