Performance Budget

A set of agreed-upon limits on performance metrics or resource quantities that a team commits not to exceed. Prevents regressions from shipping.

Definition

A performance budget is a contract among developers, designers, and stakeholders setting hard limits on performance. Budgets can be quantity-based (max 300 KB JS, max 50 HTTP requests) or metric-based (LCP under 2.0 s). Enforced in CI/CD to block deploys exceeding limits.

Why Budgets Matter

Every new feature adds weight. Without a budget, teams accumulate bloat until the site is slow. A budget forces tradeoffs upfront: 'Add this library, but remove something equal in weight.'

Common Misunderstandings

Budgeting only page weight is insufficient. A 200 KB page can have 500 ms of main thread blocking. Budget both quantity and metric dimensions. Budgets need periodic review.

Implementation

Use Lighthouse CI with budget assertions, bundlesize, or webpack performance hints. Define budgets in version control. Fail CI on budget exceedance.

Note

Starting point: 300 KB JS, 100 KB CSS, 2 MB images, under 50 requests.

In code

{
  "ci": {
    "assert": {
      "assertions": {
        "categories:performance": ["error", {"minScore": 0.9}],
        "resource-summary:script:size": ["error", {"maxNumericValue": 300000}]
      }
    }
  }
}

Common questions

Q: What if we need to exceed budget?

A: Discuss deliberately. A budget is a baseline, not a wall.

Key takeaways:

• Enforceable limit on metrics/resources.

• Prevents gradual bloat.

• Budget both quantity and metrics.

• Enforce in CI/CD.