CLI tool
siddharthkp/bundlesize avatar
siddharthkp/bundlesize

bundlesize turns a file budget into a failing build, and asks for a token to do it

Keep your bundle size in check

4,463 stars176 forksJavaScriptMIT

At a glance

What is it?
A dev dependency that gzips (or brotlies) your build output, compares each file against a maxSize you set, and can report the result back to a pull request through a GitHub status. The costs are the GitHub token, five hand-set CI variables on other runners, and a release history that is uneven.
Who is it for?
Take it for a JavaScript project that already builds to disk, has one vendor chunk you care about, and runs on Travis CI, CircleCI, Wercker or Drone where the author shipped the status wiring. Pass on it if your CI is anything else, because the five variables the README asks for are manual, or if you want a project-wide brotli setting, because the compression choices are per file rather than a project default.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 109 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • siddharthkp/bundlesize4,463 ★ · -7
Star history
Repository2026-09-232026-11-14
siddharthkp/bundlesize4.5k4.5k

-7 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One dev dependency and one script entry is the whole setup

bundlesize installs as an ordinary dev dependency and runs from `package.json` scripts, so it lands in front of `npm test` rather than in a separate pipeline definition:

sh
npm install bundlesize --save-dev

# or

yarn add bundlesize --dev
json
"scripts": {
  "test": "bundlesize"
}

You can also call it through `npx`, which the README ties to NPM 5.2 and later:

sh
npx bundlesize

The bare command reads whatever configuration it can find, so the interesting decisions sit in that configuration rather than in the invocation. It measures files that already exist on disk, which is why the script belongs after your build step and not before it.

A maxSize budget is compared after gzip unless the file says otherwise

Every entry pairs a path with a limit written as a string, so the unit is part of the value:

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

Compression is on by default and it is the gzipped size that gets compared, not the file on disk. A project that ships brotli instead sets it per entry:

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

And a project that ships no compressed variant at all turns it off:

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

The cost of that design is repetition: a mixed project has to repeat `"compression"` on every entry that shares a setting, because there is no project-wide default in the two documented config shapes.

A glob path becomes one row per matched file

Build tools that append a hash to output names make literal paths useless, so entries accept glob patterns instead:

json
{
  "files": [
    {
      "path": "build/**/main-*.js",
      "maxSize": "5 kB"
    },
    {
      "path": "build/**/*.chunk.js",
      "maxSize": "50 kB"
    }
  ]
}

One entry can therefore stand for many files, and the README is explicit that a pattern matching several files produces a new row for each of them. That is the point of the feature and also its trap: the budget you wrote as one number becomes a limit applied separately to every match, so a pattern that catches forty small entry chunks passes while a pattern that catches one vendor bundle is still a single decisive number. Naming your output pattern deliberately is the whole job here.

The budget lives in package.json or in a config file, in two different shapes

The same array can sit under a `bundlesize` key in `package.json`:

json
{
  "name": "your cool library",
  "version": "1.1.2",
  "bundlesize": [
    {
      "path": "./build/vendor.js",
      "maxSize": "3 kB"
    }
  ]
}

or in `bundlesize.config.json`, where it is wrapped in a `files` object:

json
{
  "files": [
    {
      "path": "./dist.js",
      "maxSize": "3 kB"
    }
  ]
}

The wrapper is not cosmetic, and it is the first thing to get wrong when you split the config out. Moving the array from one home to the other means adding a level, not just moving text. A second file can also be named explicitly, which is how a monorepo keeps one budget per package:

sh
bundlesize --config configs/bundlesize.json

The repository carries its own `bundlesize.config.json` at the root and an `examples/` directory holding a config plus a `package.json`, so both layouts have a working reference to copy.

A GitHub status check needs a token with repo:status scope

The part that makes this more than a local number is the commit status on pull requests, and that part is not free of setup. The README says it currently works with Travis CI, CircleCI, Wercker and Drone, and the sequence is fixed: authorize bundlesize for status access through the link it gives you, copy the token, then add that token to your CI project settings as an environment parameter named `BUNDLESIZE_GITHUB_TOKEN`.

That token is a write credential for your repository's statuses. Anyone holding it can report status on any repository the authorization covers. There is no documented way to scope it narrower than the authorization page allows, and no documented way to skip the token while keeping the status, so a team that does not want a shared secret in its CI has to give up the pull request row. Local runs do not need the token at all, which means the same command behaves differently in the two places you will run it.

Any other CI runner means five variables set by hand

Outside those four services, the README asks you to supply five environment variables yourself:

- `CI_REPO_OWNER` given the repo `https://github.com/myusername/myrepo` would be `myusername` - `CI_REPO_NAME` given the repo `https://github.com/myusername/myrepo` would be `myrepo` - `CI_COMMIT_MESSAGE` the commit message - `CI_COMMIT_SHA` the SHA of the CI commit, in Jenkins you would use `${env.GIT_COMMIT}` - `CI=true` usually set automatically in CI environments

So a runner that does not define them means copying the owner and repository slug out of your own remote by hand. `CI_COMMIT_MESSAGE` and `CI_COMMIT_SHA` are the two that vary per build, which makes them the two a pipeline template has to wire up. The repository's own TODO list still carries automating that setup and adding AppVeyor, tracked as issue 234, so treat the manual path as the intended state rather than a gap someone closed later. The README closes the section with an offer to help when you get stuck, which tells you how much of this path is meant to be hand assembled.

bundlesize-pipe takes a file on stdin, and no page documents it

The `bin` map in `package.json` publishes three executables: `bundlesize`, `bundlesize-init` pointing at `src/init-status.js`, and `bundlesize-pipe` pointing at `pipe.js`. The README has a section for the first and nothing for the other two, which leaves the pipe mode visible only through the test scripts:

json
"test:default": "node index && cat pipe.js | node pipe --name pipe.js --max-size 1kB",
"test:no-compression": "cat pipe.js | node pipe --compression none --name pipe.js",
"test:brotli-compression": "cat pipe.js | node pipe --compression brotli --name pipe.js"

Those three lines are the only written description of the interface: a file arrives on stdin, and `--name`, `--max-size` and `--compression` carry the same three things a config entry carries. It is enough to work out that the pipe exists for build steps that produce a single artifact without a config file, but you are reading test commands as documentation. `bundlesize-init` is even thinner: nothing outside that `bin` line mentions what it initialises. Pin the version before relying on either, since the flags are visible in a 0.18.2 manifest and nothing states that they are stable.

Three neighbouring tools solve the same job in different ways

The README lists three alternatives and states the difference in one clause each. BuildSize is a GitHub App that needs no manual configuration, so it moves the budget out of your repository and into someone else's settings. travis-weigh-in is written in Python rather than Node.js, which matters only if your pipeline already has a Python stage. size-limit uses webpack and builds the files for you, so it takes over the build step instead of measuring its output.

That last difference is the one to weigh against bundlesize. bundlesize measures artifacts that exist, which keeps it tool agnostic and works with whatever produced your chunks, at the cost of running after the build and holding the budget in a file you maintain. A webpack-coupled tool can compute the budget from the graph itself, which is less manual work and useless the moment your bundler is not webpack. The release history is worth reading before choosing any of them: v0.18.0 in 2019 added the option to move the config to a different file, v0.18.2 in 2024 was a security patch, and the last push landed on 2026-07-29.

Editorial conclusion

Take it for a JavaScript project that already builds to disk, has one vendor chunk you care about, and runs on Travis CI, CircleCI, Wercker or Drone where the author shipped the status wiring. Pass on it if your CI is anything else, because the five variables the README asks for are manual, or if you want a project-wide brotli setting, because the compression choices are per file rather than a project default. Check first that a glob path actually matches your output names.

Frequently asked questions

Does bundlesize compare the raw file size or the compressed size?

The compressed size, by default. bundlesize gzips your build files before comparing, and each entry can set `"compression": "brotli"` or `"compression": "none"` instead.

Where can the bundlesize config file live?

In `package.json` under a `bundlesize` key as a bare array, or in a separate file such as `bundlesize.config.json` where the array sits inside a `files` object. A different filename can be passed with the `--config` flag.

Does bundlesize need a GitHub token to report status on pull requests?

Yes. You authorize bundlesize for status access, copy the token, and add it to your CI settings as the `BUNDLESIZE_GITHUB_TOKEN` environment parameter. The status integration is listed for Travis CI, CircleCI, Wercker and Drone.

Can I run bundlesize without a config file?

Yes, through CLI flags such as `bundlesize -f "dist/*.js" -s 20kB`, or through `npx bundlesize`. The README states that this approach is not recommended and might be deprecated in a future version, and points at `package.json` configuration for anything more granular.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. siddharthkp/bundlesize on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/siddharthkp-bundlesize.svg)](https://hysenlabs.com/projects/siddharthkp-bundlesize)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/siddharthkp-bundlesize.svg)](https://hysenlabs.com/projects/siddharthkp-bundlesize)

Was this useful?