Bundle Size by Utilarium docs
The upload API, the one-line uploader, flags, budgets, limits and the badge. Everything a CI job needs to send the size of a build.
On this page
The words
- Repo: a code repository, such as
acme/widgets. It has one owner (the person who added it) and a default branch. - Upload: the sizes of one build for one commit, one branch and one flag.
- Flag: the part of the repo that a build is. In a monorepo, the project folder (
apps/web,packages/ui). - Chunk: one file of the build with its raw bytes and its gzip bytes (gzip level 9). The kind is
js,css,assetorother. - Route: one page of the build. Its size is the html file and the script and style files that the page loads with tags, each file once.
- Total: the sum of the chunks of an upload. The total of a repo on a branch is the sum of the latest upload of each flag (a flag with no upload for a commit keeps its latest earlier upload).
- Base: the build that a build is compared with. It is the previous upload of the same flag on the default branch of the repo.
- Retention: Bundle Size by Utilarium keeps the last 100 uploads of each flag on each branch. When a new upload lands, older ones are deleted with their chunks and routes, and so are commits left with no upload.
The uploader
One line sends the sizes of a build from your CI. It needs Node 20 or later and no install. It walks the build directory of Vite, measures every file (raw bytes and gzip level 9 bytes) and sends the JSON of the API below, gzipped. The token is the variable BUNDLE_SIZE_TOKEN.
BUNDLE_SIZE_TOKEN=bsz_... npx -y https://bundle-size.utilarium.app/cli.tgz \
--dir dist --flag webcurl -fsSL https://bundle-size.utilarium.app/upload.mjs | BUNDLE_SIZE_TOKEN=bsz_... node - \
--dir dist --flag web--dir: the build directory (defaultdist). Source maps (.map) are not measured. An html file is a route; the kind of the other files comes from the extension.--flag: the part of the repo (defaultdefault); in a monorepo, one upload for each project.--commit(default: the commit variable of your CI, thengit rev-parse HEAD) and--branch(default: GitHub, GitLab, Buildkite, CircleCI and other CI variables, then git).--url(orBUNDLE_SIZE_URL) for another server.--strict: exit 1 when the upload fails, or when the build is over its budget. Without it the uploader prints one line and the build goes on, and it exits 0.
The uploader does not follow scripts that a page loads later (dynamic imports). Those files are chunks, and they are in the total, but not in the size of a route.
After a good upload the uploader prints these lines (the second one only when the budget fails). The address is the commit page. A failed upload prints one line that starts with bundle-size upload failed: and the reason.
bundle-size uploaded: web 63.7 kB gzip, 207.6 kB raw https://bundle-size.utilarium.app/r/acme/widgets/commit/0123456789abcdef0123456789abcdef01234567
bundle-size: BUDGET FAILED for web: 71.2 kB is over the limit of 70.0 kBIn your CI
# .github/workflows/bundle-size.yml
name: bundle-size
on: [push, pull_request]
jobs:
size:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci && npm run build
- name: Upload the size
run: npx -y https://bundle-size.utilarium.app/cli.tgz --dir dist --flag web --strict
env:
BUNDLE_SIZE_TOKEN: ${{ secrets.BUNDLE_SIZE_TOKEN }}# .gitlab-ci.yml
bundle-size:
image: node:22
script:
- npm ci && npm run build
- npx -y https://bundle-size.utilarium.app/cli.tgz --dir dist --flag web --strict
# Set BUNDLE_SIZE_TOKEN in Settings > CI/CD > Variables (masked).Save the token as a secret named BUNDLE_SIZE_TOKEN. On Buildkite, CircleCI, Jenkins or any other CI, run the same line after your build.
Pull request runs
On a pull_request run, actions/checkout checks out a merge commit, not the head of the pull request. By default the upload belongs to that merge commit. To upload the head commit, pass it with --commit.
- name: Upload the size
run: >-
npx -y https://bundle-size.utilarium.app/cli.tgz --dir dist --flag web --strict
--commit "${{ github.event.pull_request.head.sha || github.sha }}"
env:
BUNDLE_SIZE_TOKEN: ${{ secrets.BUNDLE_SIZE_TOKEN }}POST /api/v1/upload
Send the header Authorization: Bearer <token> (the token names the repo; it starts with bsz_) and Content-Type: application/json. The body may be gzip, with Content-Encoding: gzip.
gzip -c build.json | curl --fail-with-body \
-X POST https://bundle-size.utilarium.app/api/v1/upload \
-H "Authorization: Bearer $BUNDLE_SIZE_TOKEN" \
-H "Content-Type: application/json" \
-H "Content-Encoding: gzip" \
--data-binary @-The body
{
"commit": "0123456789abcdef0123456789abcdef01234567",
"branch": "main",
"flag": "apps/web",
"chunks": [
{ "name": "assets/index-AbC123xy.js", "kind": "js", "raw": 182340, "gzip": 58112 },
{ "name": "assets/index-Zx9Qw3Lm.css", "kind": "css", "raw": 24310, "gzip": 5120 },
{ "name": "index.html", "kind": "other", "raw": 910, "gzip": 480 }
],
"routes": [
{ "path": "/", "raw": 207560, "gzip": 63712 }
]
}commit: 40 lower case hex digits.branch: up to 200 characters, no spaces.flag: up to 200 characters ofA-Z a-z 0-9 . _ / -, with no empty,.or..part.chunks: the list of files, at least one.nameis the path in the build directory (1 to 300 characters, no control character).kindisjs,css,assetorother.rawandgzipare whole numbers of bytes.routes: optional, the list of pages.pathstarts with/.rawandgzipare whole numbers of bytes.
Any other field is refused, so a typo does not go unnoticed. Two chunks cannot have the same name, and two routes cannot have the same path. The service adds the chunks to make the totals.
What grew since the base
The commit page compares each flag of the commit with its base: the previous upload of the flag on the default branch. For a build on the default branch, that is the upload before it. The page lists the chunks that are added, removed, grown or shrunk by gzip bytes, the biggest growth first, and then the same for routes. A chunk with the same gzip size in both builds is not listed.
To match a chunk across builds, the service removes the content hash of Vite from the name: assets/index-AbC123xy.js and assets/index-Zx9Qw3Lm.js are both assets/index-*.js. A hash is 8 characters of letters, digits, _ and - after a - and before a dot. An 8-letter word such as -settings is not a hash. When two chunks have the same name once the hash is removed, their sizes add up.
Budgets
A budget belongs to one flag of a repo. The owner sets it in the settings of the repo. It has two parts, and both are optional:
budgetGzip: the most gzip bytes that the whole build may have.budgetGrowthPercent: the most the gzip total may grow, in percent, against the base build.
Each upload is checked on arrival. The upload answer has budget with ok, limit (the gzip limit, or null), actual (the gzip total of this build) and growthPercent (against the base, two decimals, or null when there is no base). The build is not ok when it is over the gzip limit, or when the growth is over the growth limit. A growth limit cannot fail when there is no base. A build over its budget is stored anyway. With --strict the uploader exits 1.
The settings page uses a call that you can also make from a signed-in browser: PUT /api/v1/repos/<owner>/<name>/budget with this JSON. A value of null removes a limit.
{ "flag": "apps/web", "budgetGzip": 70000, "budgetGrowthPercent": 5 }Limits
- 8 MB for the body, counted as sent and again after gunzip.
- 5000 chunks and 1000 routes in one upload.
- 20 repos for each person, 20 upload tokens and 50 flags for each repo.
- The last 100 uploads of each branch and flag.
- 10 repos or tokens made in a minute.
Answers
{
"ok": true,
"id": 42,
"url": "https://bundle-size.utilarium.app/r/acme/widgets/commit/0123456789abcdef0123456789abcdef01234567",
"totals": { "raw": 207560, "gzip": 63712 },
"budget": { "ok": true, "limit": 70000, "actual": 63712, "growthPercent": 1.25 }
}201: stored.urlis the commit page (it opens in the dashboard after you sign in).totalsare the raw and gzip bytes of the build.400{"ok":false,"error":"..."}: the body is not valid; the error says why.401: no token, or a wrong or revoked one.403: the repo has 50 flags already.413: the body is over 8 MB.
One upload for each repo, commit and flag: a second upload replaces the first (its chunks and routes too), so you can send again after a retry.
Badge
A badge shows the gzip total of the default branch in kB. It is off until you turn on "Public badge" in the settings of the repo. Add ?flag=apps/web for one flag.
The address always answers with an image (status 200, cached for 5 minutes), so a README shows it everywhere, GitHub included. When the repo does not exist, when the badge is off and when the repo has no upload yet, the image is the same grey "bundle size | no data", so it does not tell a private repo from one that is not there. It is the same for a flag with no upload.
PR status check
PR status check: planned. It needs a GitHub App, and that App is not set up. It is not live. Until then, use --strict in your CI: the job fails when a build is over its budget.