"The site feels slow" is one of the least actionable sentences in software. Slow where? Compared to what? By how much? Without an answer, performance work becomes a vibe — someone occasionally notices the app feels sluggish, does a bit of optimisation, and moves on until the next time it gets bad enough to complain about. A performance budget replaces that cycle with something you can actually manage: a set of numbers that a change either respects or violates.
I've watched teams with genuine talent ship steadily slower products, not because anyone was careless, but because nothing ever said stop. A budget is the thing that says stop.
What a budget actually is
A performance budget is a set of limits on the things that determine how fast your site feels, agreed in advance and enforced automatically. It usually has two kinds of numbers:
- Outcome metrics — the things users feel, expressed as targets. The Core Web Vitals are the standard vocabulary here: how quickly the main content appears, how quickly the page responds to input, and how much the layout shifts around while loading.
- Proxy metrics — the things you control directly, expressed as ceilings. The total JavaScript shipped to the browser, the total image weight per page, the number of network requests. These are levers; the outcome metrics are results.
You need both. Outcome metrics tell you whether users are having a good time; proxy metrics tell you which lever to pull when they aren't. A budget with only outcome numbers tells you that you failed but not why.
Set the number from your users, not your laptop
The most common way a budget goes wrong is being set against the wrong baseline. If you decide what "fast enough" means by testing on a modern laptop on office internet, your budget will be generous to the point of meaningless, because almost nothing feels slow in those conditions.
Set the budget against a realistic device and connection — a mid-range phone on a mediocre mobile network, because that's who a large share of real visitors are. Then pick targets that are ambitious but achievable: meaningfully better than where you are now, not a fantasy you'll quietly abandon. A budget you routinely blow through teaches the team to ignore budgets.
An aspirational budget nobody meets is worse than no budget — it trains everyone to treat the warning as noise.
Enforce it where regressions happen
Here is the part that separates a real budget from a document nobody reads: the budget has to run in your pipeline, on every change, and it has to be able to fail the build. A number that lives in someone's head, or in a wiki, will be violated within a month and nobody will notice until the site is slow again.
The mechanism can be simple. A CI step that builds the app and checks the bundle sizes against your ceilings. A performance check that loads key pages under throttled conditions and compares the outcome metrics to your targets. When a pull request pushes a number past its limit, the check goes red and the author sees it before it merges, while the cause is fresh and the fix is cheap. That timing is everything — a regression caught in review costs minutes; the same regression caught in production costs an investigation.
Make it negotiable, but explicitly
Sometimes you genuinely need to break the budget — a critical feature ships a heavy dependency, and the value is worth the weight. That's fine. The point of a budget isn't to make performance sacred; it's to make the trade-off visible and deliberate instead of accidental.
So when someone needs to exceed a limit, the answer isn't to quietly raise the number until it stops complaining. It's a conscious decision: we're spending part of our budget here, on purpose, because this feature earns it — and now we know we owe some optimisation elsewhere to pay it back. A budget you can consciously overspend is healthy. A budget you silently inflate is already dead.
Start smaller than you think
If you have no budget today, don't try to build the perfect one. Pick the single metric that hurts most — usually total JavaScript, because it's the one that quietly grows forever — put a ceiling on it slightly below where you are now, and wire a check into CI that fails when a change exceeds it. That one guardrail will do more than a beautiful spreadsheet of twenty metrics that nobody enforces.
Then add metrics as you learn which ones your team actually regresses. The budget grows into the shape of your real problems, which is the only shape worth having.
The point of all of it
A performance budget isn't really about performance. It's about turning an invisible, slow-moving form of decay into a visible event that happens at a specific moment — in a pull request, in front of the person who caused it, while it's still cheap to fix. Get that loop in place and speed stops being a periodic crisis and becomes just another thing the build checks, like tests. That's the whole game.