You do not usually wake up one morning to discover your site has slowed. What actually happens is more annoying. A date picker adds 38 KB. Marketing ships a heavier hero image. A helpful SDK pulls in three more transitive dependencies. Nobody notices, because each change looks harmless in isolation. Then one sprint later, your product page feels sticky on mid-range Android, and your Core Web Vitals chart starts looking like a slow leak in a tire.
That is exactly what performance budgets are for. In plain English, a performance budget is a set of hard limits for the things that make pages feel fast or slow, such as JavaScript bytes, image weight, request counts, or user-facing metrics like Largest Contentful Paint. The idea is simple: stop regressions before they reach production. Performance budgets are less about a single heroic optimization sprint and more about preventing slow creep while the team continues shipping features.
The practical move is to treat performance like test coverage. You do not “care about quality” in the abstract; you embed it in the pipeline so that bad changes fail early. That mindset is what turns performance from a quarterly cleanup project into a release gate.
The teams doing this right are using budgets as guardrails, not aspirations
When we pulled together the current guidance, the pattern was refreshingly consistent. Addy Osmani, Engineering Lead at Google Chrome, has argued that performance tends to regress as soon as teams return to normal feature work, which is why budgets matter: they force earlier tradeoff decisions about what is actually worth shipping to users. Katie Hempenius, formerly on Google’s web performance education team, has described Lighthouse budgets as a practical way to catch both metric regressions and resource bloat before release. Tammy Everts, co-founder at SpeedCurve, makes the most useful distinction of the three: goals are where you want to end up, budgets are the practical ceilings that keep you from getting slower on the way there.
The broader web data explains why this matters. Recent Web Almanac findings show that many sites still fail to achieve “good” Core Web Vitals consistently, especially on mobile. That means fast, stable experiences are still not the default. Performance remains a competitive advantage, particularly on constrained devices and unreliable networks, where bundle bloat hurts more, and user patience runs out faster.
The takeaway is not “track everything.” It is the opposite. Start with a few measurements that map to user pain and release risk, then enforce them automatically. Budgets fail because teams make them vague, sprawling, or political. The winning version is boring, explicit, and tightly integrated with pull requests.
Pick budgets that map to real regressions
A good budget catches the kinds of mistakes your team actually makes. If your front end keeps pulling in chunky libraries, start with JavaScript and entrypoint size. If CMS users routinely upload enormous media files, performance budgets are impacted. If you already know your main experience is sensitive to rendering speed, performance budgets, LCP, or the Lighthouse performance score as a proxy in CI. A useful mental model is to divide budgets into timing-based, quantity-based, and rule-based limits.
Here is the simplest way to think about it:
| Budget type | What it catches | Best CI use |
|---|---|---|
| Bundle size | Dependency creep, oversized entrypoints | Build step |
| Resource weight/count | Heavy images, too many requests, third parties | Lighthouse CI |
| User-facing metric | Slow render or interaction regressions | Preview or staging test |
For most product teams, the first version should include one budget per row. That gives you one fast build-time guardrail, one page-composition guardrail, and one user-facing signal. A page might cap JavaScript on mobile, set an image-size ceiling, or require a minimum Lighthouse performance score.
A worked example makes this concrete. Say your checkout page currently ships 210 KB of compressed JavaScript, 480 KB of images, and scores 88 in Lighthouse on a representative preview environment. Do not set tomorrow’s dream target today. Set an enforced ceiling slightly above today’s stable baseline, maybe 220 KB JS, 550 KB images, and a Lighthouse floor of 85. Once the team holds that line for a few sprints, ratchet down. That “freeze, then reduce” approach is usually far more durable than setting aggressive targets nobody believes.
Build the pipeline in four moves
1. Put one budget in the build itself.
This is your cheapest failure point. If you use webpack, it already supports performance hints, and you can configure it so oversized assets fail the production build. You can also set maximum asset and entrypoint sizes in bytes. Angular teams have a similar advantage because Angular CLI supports build budget configuration directly, and Next.js gives you bundle analysis tools so you can see what is inflating client or server bundles before it lands.
2. Add page-level budgets with Lighthouse CI on every PR.
Build-time budgets only tell you the bundle got bigger. They do not tell you that a new route now makes 15 extra requests, or that an image-heavy hero pushed total weight out of range. Lighthouse CI is built for this layer. You can use assertions to fail builds when pages miss predefined audits or performance budgets, and its config supports a dedicated budgets file. One small gotcha worth remembering is that some Lighthouse CI assertions use bytes, while budget files often use kilobytes. That unit mismatch has wasted many afternoons.
[
{
"path": "/checkout",
"resourceSizes": [
{ "resourceType": "script", "budget": 220 },
{ "resourceType": "image", "budget": 550 },
{ "resourceType": "total", "budget": 1200 }
],
"resourceCounts": [
{ "resourceType": "third-party", "budget": 6 }
]
}
]
This kind of file is intentionally unglamorous. That is the point. It turns performance into a merge condition instead of a dashboard nobody opens.
3. Test the right environment, not just localhost fantasy land.
A surprising number of “performance budgets in CI” setups are really “bundle assertions on a machine with no latency.” Useful, but incomplete. Lighthouse CI becomes much more credible when it runs against a preview deployment or staging URL that resembles production routing, image transforms, and third-party tags. That means you can test the actual thing you are about to ship, not the toy version.
4. Close the loop with real-user data after deploy.
CI should block obvious regressions. It should not pretend to be your entire performance program. Synthetic budgets catch structural problems early, while field data tells you whether real users are actually paying the price. In practice, that means you should review post-deploy field metrics for your highest-value pages and adjust budgets every few weeks rather than freezing them forever.
Use framework-native tooling where it helps, then standardize on one release gate
This is where many teams overcomplicate things. They mix five analyzers, three dashboards, and a custom script graveyard, then nobody trusts the numbers. A cleaner pattern is to let each framework do what it is good at, while keeping one standard gate for release.
If you are on WebPack, native performance hints are the easiest first stop, especially for entrypoint and asset ceilings. If you are on Next.js, bundle analyzers are excellent for finding why a module is present, not just that it is large. Angular projects can centralize build behavior in the CLI configuration, which makes team-wide budget enforcement easier than ad hoc scripts hidden in one engineer’s shell history.
But your final gate should usually be the same for every app: a PR check that says pass or fail based on a small set of agreed budgets. That consistency matters more than tooling purity. When every repo reports different signals, performance becomes a debate. When every repo fails on the same kinds of regressions, it becomes an engineering norm.
One practical trick: keep a “warning band” outside the hard fail. For example, fail the PR if checkout JS exceeds 220 KB, but post a warning comment if it grows by more than 10 KB even when still under budget. That gives you room to catch creep before the line is crossed, without turning every small change into a release blocker.
The common failure modes are social, not technical
The hardest part is almost never writing the config file. It is agreeing on what matters, and then sticking to it when deadlines get messy.
The first mistake is setting budgets to ideal targets instead of current baselines. That creates instant alert fatigue, and people learn to ignore the system. The second is budgeting too many pages and metrics at once. Start with minimum viable budgets. Your homepage, product detail page, signup, checkout, search, or article template will usually tell you most of what you need to know.
The third mistake is pretending performance scores are enough. Lighthouse scores are useful, especially in CI, but they can hide the reason a page regressed. A score drop is the smoke alarm, not the fire report. Pair score-based assertions with at least one concrete resource budget so engineers know what to fix.
The last mistake is never revisiting the thresholds. Budgets should tighten as the system gets healthier, and occasionally loosen when architecture changes make an old threshold meaningless. That is not failure. That is maintenance. The real failure is keeping a budget that nobody believes.
FAQ
Should you budget bytes or metrics?
Both, but not in equal amounts. Byte budgets are more deterministic and fail earlier in the pipeline. Metric budgets are closer to user experience. A strong starter setup is one JS budget, one image or total-weight budget, and one Lighthouse or rendering metric.
Where should the budget fail, PR or deploy?
PR is best for developer feedback, and staging or preview is best for realism. Mature teams often do both: cheap bundle checks during build, then Lighthouse CI against a preview URL before merge.
What pages deserve budgets first?
Start with the pages that make money or absorb the most traffic. Product detail, category, checkout, home, article, and search pages are common first picks.
How often should you change thresholds?
Usually, every two to four weeks, after reviewing stable data. Tighten when you have proven improvements, not because the team feels ambitious on a Monday.
Honest Takeaway
The easiest way to think about performance budgets is this: they are not a performance strategy; they are a merge policy. Their job is to stop accidental regressions from slipping through the release conveyor belt. If you only remember one thing, make it this one: start with budgets that reflect today’s reality, wire them into pull requests, and ratchet them down slowly.
Teams that succeed here do not have more willpower. They have fewer decisions left for humans to make at the end of a sprint. That is what CI/CD is for.
