Performance Budgets: Preventing Slow Sites Over Time

Sites get slower when no one is watching. Performance budgets give you a line in the sand: when size or timing exceeds it, the build or deploy fails or triggers a review.

What to budget

Size: Total JS (or CSS) size, or per-route size. For example, “main bundle under 200 KB gzipped” or “homepage JS under 300 KB.” Timing: Lighthouse metrics (LCP, INP, CLS) or custom timings. For example, “LCP under 2.5s on mobile.” Start with one or two metrics (e.g. total JS and LCP) so the team can act on them. Add more as you stabilize.

Setting the numbers

Base the budget on current state or a target. If the site is already fast, set the budget slightly below current values so regressions are caught. If it’s slow, set an achievable target and tighten over time. Use real data: e.g. “75th percentile LCP from CrUX is 2.2s, budget is 2.5s.” For JS, consider device and network: 200 KB on 3G is different from 200 KB on cable; pick a number that matches your users and device mix.

Enforcing in CI

Run Lighthouse (or a similar tool) in CI on a representative URL. Compare the result to the budget; fail the build or block merge if the budget is exceeded. Use lighthouse-ci or a custom script that parses the report and exits with a non-zero code when metrics are out of range. Budgets can be “warning” (log but don’t fail) at first, then “error” once the team is used to them. Ensure the test environment is consistent (same URL, same config) so results are comparable.

# Example: Lighthouse CI step
- name: Run Lighthouse
  run: npx lhci autorun
  env:
    LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_TOKEN }}

Configure lhci to assert on LCP, CLS, and perhaps total byte size so every PR is checked.

Evolving budgets

Review budgets periodically. When you optimize and metrics improve, tighten the budget so you don’t regress. When you add a justified feature that increases size, adjust the budget and document why. Budgets are a tool, not a substitute for judgment—use them to catch regressions and keep performance visible over time.

Summary

Set budgets for size (e.g. JS) and timing (e.g. LCP). Base numbers on current or target metrics. Enforce in CI with Lighthouse or similar so builds fail when budgets are exceeded. Revisit and tighten as the site improves. That’s how performance budgets prevent slow sites over time.