Performance budgets that actually hold

Every team says performance matters. Far fewer make it impossible to regress. The difference is not talent or good intentions — it is whether the budget is enforced by a machine that can say no.

A performance budget is a hard ceiling on the things that make a page slow: JavaScript shipped, total bytes, and the timings a user actually feels. Written down, it is a wish. Wired into CI, it is a contract.

Start from what the user feels

We budget the metrics that map to perception, not vanity numbers. Largest Contentful Paint under a second. Interaction latency under 200ms. Cumulative Layout Shift at zero. Everything else is in service of those.

A budget nobody enforces is a wish. A budget the build enforces is a promise you can keep.

Make it a build gate

The budget lives in the repo and runs on every pull request. If a change pushes a route over its JavaScript ceiling or its LCP target, the build fails — before the code reaches a preview, let alone production.

{
  "resourceSizes": [
    { "resourceType": "script", "budget": 120 },
    { "resourceType": "total",  "budget": 300 }
  ],
  "timings": [
    { "metric": "lcp", "budget": 1000 }
  ]
}

Why per-route matters

A single global budget hides regressions: a heavy dashboard averages out against a light marketing page. We budget per route, so the page that got slow is the page that fails, and the person who slowed it is the person who fixes it — while the context is still fresh.

What it buys you

• Performance stops being a quarterly clean-up project and becomes a property of the codebase.
• Reviews get honest: the number is on the PR, not in someone’s memory of last month.
• New engineers inherit the standard automatically — the build teaches it to them.

None of this is exotic. It is a config file, a CI step, and the discipline to let the machine hold the line. That is the whole trick — and it is why our sites are still fast a year after launch.