Performance Budgets

Performance budgets create measurable constraints — performance should be managed intentionally, not optimised later.

01 — Purpose

Measurable constraints

Performance budgets create measurable frontend constraints — performance should be managed intentionally.

Without limits, pages grow: another dependency, another hero image, another analytics script. Budgets turn performance from a vague goal into a number teams can enforce in review and CI.

See Core Web Vitals and performance monitoring for what to measure against budgets.

02 — Principles

Budgets protect performance from entropy

Reduced regression, clearer engineering decisions, and healthier long-term performance.

  • page weight — total transfer size per template
  • JS size — parsed and executed script per route
  • image payload — bytes and count on key landing pages
  • render timing — LCP, INP, and CLS thresholds per template

03 — Practice

Setting and enforcing budgets

Define limits, measure in CI, and fail builds on regression.

  • start with your worst and best templates — set realistic baselines
  • enforce JS budgets in CI — bundle analyser on pull requests
  • track CWV in production — alert when p75 crosses budget; see performance monitoring
  • include third-party weight — see third-party performance
  • document exceptions — who approved going over budget and for how long

04 — Avoid

Budget failures

Undefined limits and “optimise later” thinking guarantee drift.

  • undefined limits — no agreed numbers for JS, images, or LCP
  • “optimise later” thinking — shipping heavy pages and never returning
  • budgets only in spreadsheets — not wired to CI or release gates
  • one global number for every route — homepage and dashboard need different budgets
  • ignoring regressions — green Lighthouse once, no ongoing check

05 — Close

Make over-budget visible

A budget nobody sees is a suggestion.

Put budgets in the PR checklist. When a change exceeds a limit, the author explains why or trims scope. Performance stays a team habit, not a launch-week panic.

See JavaScript cost, image delivery, and performance review checklist.