Writing a performance budget your team will keep
A budget only works if it is specific, enforced automatically, and owned by someone.
Why budgets fail
Most performance budgets are written once, presented in a meeting, and forgotten within a month. The page grows a little with every release, nobody notices any single change, and a year later the site is twice as slow as when the budget was set. The problem is rarely the numbers. It is that nothing enforces them.
Pick metrics people can act on
A good budget mixes two kinds of limits:
- Quantity limits: total JavaScript, total image weight, number of requests, number of third-party origins.
- Timing limits: largest contentful paint, interaction to next paint, cumulative layout shift.
Quantity limits are easy to check on every pull request because they do not depend on network conditions. Timing limits reflect what visitors actually feel but are noisier to measure. Use both.
Make the numbers specific
"Keep the site fast" is not a budget. "The product page ships at most 170 kilobytes of compressed JavaScript" is. Write limits per page type, because a checkout and a blog post have very different needs, and attach each limit to the page where it applies.
Enforce it in CI
The single most effective step is to fail the build when a limit is exceeded. That turns a vague cultural value into a concrete conversation at the moment a change is proposed. The engineer adding a dependency sees the cost immediately and can choose a lighter alternative, split the code, or argue for raising the limit.
That last option matters. A budget that can never change will be bypassed. Make raising a limit possible, but make it a deliberate decision with a reason written down.
Track the trend
A chart of bundle size over the last hundred merges tells a story no single check can. It shows the slow creep, the occasional cleanup, and the release that doubled a page's weight. Put that chart somewhere the team sees it every week.
Assign an owner
Every budget needs a person who notices when it is under pressure and starts the conversation before it breaks. Without an owner, the budget is everyone's concern, which means it is no one's.
Revisit quarterly
Devices get faster, networks improve, and the product changes. Review the budget every quarter against field data. Tighten limits that are easily met and investigate the ones that are constantly near the edge.
Start small
If you have no budget today, begin with one number: total JavaScript on your most visited page. Set it slightly above where it is now so nothing breaks, enforce it, and lower it over time. One enforced limit beats ten aspirational ones.