Blog Why performance budgets keep teams honest
Why performance budgets keep teams honest
TL;DR A performance budget sets hard limits, on bundle size, image weight, or a Core Web Vital, and fails the build when a change exceeds them. It stops the slow, invisible creep where every feature adds a little weight until the site is sluggish and nobody knows who did it.
Every team says it cares about performance. Then a year of features ships, each adding a little weight, and the site is slow and nobody can point to the culprit. A performance budget fixes that by turning a good intention into a rule the build enforces.
The problem budgets solve
Slowness rarely arrives in one bad commit. It creeps. A library here, an analytics script there, an uncompressed image, a heavier component. No single change feels like the problem, so nobody stops it, and the sum is a sluggish site with no obvious owner.
Code review does not catch this well, because a reviewer sees one change, not the cumulative trend. You need something watching the total.
What a budget actually is
A performance budget is a hard limit on something that affects speed, enforced automatically.
- Total JavaScript bundle size stays under a set number of kilobytes.
- Images on a page stay under a weight.
- A lab Core Web Vitals metric stays under a threshold.
You wire the check into CI. When a change pushes past the limit, the build fails, exactly like a failing test. The regression becomes visible at the moment it happens, attached to the change that caused it.
Why it keeps teams honest
The value is that it removes the debate. Without a budget, "is this too heavy?" is a judgement call nobody wants to be the one to make. With a budget, the number decides. Either the change fits, or it does not and you make room, drop something, lazy-load it, or find a lighter approach.
It also puts the cost where the decision is. The person adding the heavy dependency is the one who sees the failed check, while the tradeoff is fresh, instead of a performance engineer excavating it months later.
Starting small
Do not build an elaborate dashboard nobody reads. Pick one budget that maps to real experience, total JavaScript size is a good first one, and enforce it in CI. Once the team is used to the check, add another. A couple of budgets that actually block a merge beat a wall of metrics that only get looked at after the site is already slow.
The point is not to hit a perfect score. It is to make slowness something you decide to accept, out loud, rather than something that happens to you.
FAQ
What is a performance budget?
It is a defined limit on something that affects speed, such as total JavaScript size, image weight, or a Core Web Vitals threshold. You enforce it in CI so a change that pushes past the limit fails the check, the same way a failing test does.
Why not just try to be fast?
Because good intentions lose to a hundred small additions. Each feature adds a little weight, no single one feels like the problem, and the site slowly gets slow. A budget makes the limit explicit and the regression visible when it happens.
What should I set a budget on?
Start with what you can measure and control: total JavaScript bundle size is a common, effective one. You can add image weight, request counts, or lab Core Web Vitals thresholds. Pick a few that map to real user experience, not a long list nobody watches.