Performance Budgets Teams Actually Keep
Most budgets are set once, missed twice, and quietly forgotten. The ones that stick share three properties.
A performance budget is easy to write and hard to hold. The usual pattern is familiar: a number is agreed in a kickoff document, the site launches under it, and then six months of feature work push it past the limit one small dependency at a time. Nobody notices, because nobody is looking.
Make it a build failure, not a report
The single biggest change we made was moving the budget from a dashboard into the pipeline. A dashboard is something you check when you remember. A failing build is something you deal with now.
The threshold has to be generous enough that it does not fire on noise, and strict enough that it fires before the regression ships. We settled on a hard ceiling for the main bundle and a smaller allowance for anything added per route.
Budget the thing users feel
Kilobytes are a proxy. What people experience is time to first meaningful paint and how quickly the page responds to a tap. We keep byte limits because they are easy to enforce, but the numbers that get discussed in review are the field measurements from real devices on real connections.
If your budget only measures what is convenient to measure, it will be met and the site will still feel slow.
Give regressions an owner and a deadline
When the budget fails, the pull request that broke it owns the fix. Not the platform team, not a backlog ticket for next quarter. This sounds harsh and turns out to be the humane option, because the person who added the dependency an hour ago knows exactly why, and the fix is usually ten minutes.
- One ceiling for the shared bundle, one per route.
- Fail the build, do not file a ticket.
- Measure on a mid-range phone, not a workstation.
- Review the numbers monthly, in the same meeting every time.
Allow deliberate overruns
Sometimes a feature genuinely needs the weight. A map, an editor, a charting library. The budget should have a documented way to say yes: an exemption with a named owner, a reason, and a date to revisit. Without that escape hatch, teams do not raise the limit honestly, they route around it dishonestly.
The point is the conversation
A budget that is never exceeded is probably set too high. A budget that is exceeded every week is theatre. The useful zone is in between, where the limit is hit occasionally and each occasion produces a short, specific conversation about whether the feature is worth what it costs.
