What is a performance budget in a web project's CI pipeline, and what has to be true of it before it actually prevents regressions?

## What a budget actually is A performance budget is a number, agreed before the work starts, that some measurable property of the shipped site is not allowed to exceed. "Initial JavaScript on the product page stays under 170 kB compressed" is a budget. "We care about performance" is not, because nothing can check it. The point of putting it in CI is that performance decays by accident. Nobody ships a pull request called "make the site slower"; they ship a date picker, an analytics tag, a polyfill, an icon set. Each one is defensible on its own and each one costs a few kilobytes or a few milliseconds. Six months of individually-reasonable pull requests is how a fast site becomes a slow one. A budget is the mechanism that makes the cost visible at the moment someone can still choose differently — in review, not six months later in a performance sprint. ## Two families of budget **Quantity budgets** are asserted over the build artifacts. Compressed size of the entry chunk, total JavaScript on a route, number of render-blocking requests, total image bytes, size of the CSS in the head. These are deterministic: the same commit produces the same number on any machine, so the check never flakes and the failure is easy to attribute — a named file grew by a named amount. **Metric budgets** are asserted over a measured page load: largest contentful paint, total blocking time, cumulative layout shift, time to first byte. These are closer to what a user experiences, but they are measurements, so they carry run-to-run noise and need care (repeat runs, fixed throttling) before they can block a merge. Most teams run both, because they answer different questions. A byte budget catches the cause; a metric budget catches the effect, including effects that ship no new bytes at all — a hero image that stopped being preloaded, a font that started blocking, an animation that began thrashing layout. ## Where the check runs The check belongs in the pull-request pipeline, after a **production build**. Running it against a development build measures the wrong artifact entirely: unminified code, no tree shaking, dev-only warnings. It should measure a **fixed list of representative routes** — typically the entry page plus the one or two routes that carry the most traffic or the most code — because a budget on "the site" cannot be attributed to anything, and per-route budgets can be owned by the team that owns the route. A minimal quantity check needs very little machinery. A tool such as `size-limit` reads a config listing paths and limits, measures the compressed output, and exits non-zero when a path is over: ```json { "size-limit": [ { "name": "main bundle", "path": "dist/main.js", "limit": "120 kB" } ] } ``` The exit code is the whole point. In a hosted CI system, a job that exits non-zero is a failed check, and a failed required check blocks the merge. ## Choosing the first numbers The common mistake is picking an aspirational number, watching every pull request fail, and switching the check off within a fortnight. The workable sequence is: measure what the site does today, set the budget slightly above it so the current state passes, and then **ratchet** — whenever a change lowers the real number, lower the budget to match, so the improvement cannot silently be spent again. The opposite mistake is setting the budget at exactly today's value. Then ordinary noise, or a legitimate three-kilobyte change, fails the build, and the team learns that failures are meaningless. ## Warn versus fail Not every assertion deserves to block a merge. A useful split is to **fail** on assertions that are deterministic and clearly owned — byte counts, request counts — and to **warn** on assertions that are measured and noisy while you are still learning their spread. A warning is visible in review and can be argued about; a failure stops the line. Reserving failure for checks you trust completely is what keeps people from reflexively re-running or bypassing the job. ## What a budget cannot do A budget is a ceiling, not a target. Passing it means the change did not make things worse than the agreed limit; it does not mean the page is fast, and it does not tell you what real users on real devices are experiencing. It also cannot decide policy for you: someone still has to answer what happens when a genuinely valuable feature does not fit. Answering that in advance — who may raise a budget, and what they must do in exchange — is what separates a budget that survives a year from a check that quietly gets deleted.