Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Performance Budgets and Culture

Performance Budgets

Define a performance budget with limits for metrics, file sizes and request counts, choose realistic numbers from data, and enforce them in your build and pull requests.

Pages get slower by accident. Each new feature adds a little JavaScript, each campaign adds a tag, each designer adds one more large image. No single change looks serious, but the sum is. A performance budget is a set of limits that the site must stay within, agreed in advance. When a change would break the budget, the team has to make a conscious choice: optimize something, or consciously spend the budget.

What a budget contains

Budgets come in three kinds, from user-facing to technical:

  1. Experience metrics: LCP under 2.5 s, INP under 200 ms, CLS under 0.1 (at the 75th percentile of real users), or lab proxies such as TBT under 200 ms.
  2. Quantity milestones: total JavaScript under 170 KB compressed, total page weight under 1.5 MB, at most 60 requests, hero image under 150 KB.
  3. Rule-based scores: Lighthouse performance score of at least 85 on the product page.
flowchart TB
  A["Experience metrics<br/>LCP, INP, CLS"] --> B["Quantities<br/>KB of JS, image weight, requests"]
  B --> C["Rules<br/>Lighthouse score, audits"]

Metrics are the goal; quantities are the levers you control in a build.

Prefer experience metrics for goals and quantities for enforcement, because bytes are easy to measure in a pull request before real users exist.

Choosing numbers

Do not pick numbers from thin air or copy another company's. Use data:

  • Your RUM p75 today: "We are at 3.4 s LCP, the goal is 2.5 s".
  • A budget derived from the connection: on a mid-range phone over a 4G connection, around 170 KB of compressed JavaScript is a common ceiling for a snappy start.
  • Competitors: aim to be at least 20 percent faster than the best comparable site.
  • Business targets: conversion improves as speed improves, so tie the number to money.

Start with a budget slightly better than today, so it is achievable, and tighten over time. A budget nobody can meet teaches people to ignore it.

JS Check a build against a budget

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Budgets in tools

Most build and test tools can enforce a budget.

Lighthouse budgets (a budget.json file):

JSON
[
  {
    "path": "/*",
    "resourceSizes": [
      { "resourceType": "script", "budget": 170 },
      { "resourceType": "total", "budget": 1500 }
    ],
    "resourceCounts": [
      { "resourceType": "third-party", "budget": 10 }
    ],
    "timings": [
      { "metric": "interactive", "budget": 4000 }
    ]
  }
]
Terminal
lighthouse https://staging.example.com --budget-path=budget.json

Bundler limits fail the build when a chunk grows too large. In webpack this is performance.maxAssetSize and performance.hints: "error"; in Vite you can use a plugin or a size-limit check:

JSON
{
  "size-limit": [
    { "path": "dist/assets/index-*.js", "limit": "170 KB", "gzip": true }
  ]
}

Run npx size-limit in CI, and the pull request fails when the main bundle exceeds its limit.

Budgets for third parties

Third-party code is the hardest to control, so budget it explicitly:

  • Maximum number of third-party scripts and their combined size.
  • Maximum main-thread blocking time they may cause.
  • A rule that every new tag needs an owner, a purpose and a removal date.

Handling a budget violation

When a change breaks the budget, there are only four honest choices:

  1. Optimize the new code (the best outcome).
  2. Remove something else of equal weight.
  3. Defer the new code (load it lazily or after interaction).
  4. Raise the budget with a written reason and an owner, knowing the cost.
JS A budget that tracks trends

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Looking at trends gives you a warning before the red build.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main purpose of a performance budget?

    Budgets turn performance into an explicit constraint that every change is checked against.
  2. 2. Which is the best basis for choosing budget numbers?

    Data-based numbers are credible and achievable.
  3. 3. A pull request pushes the main bundle over its size limit. What should the team do?

    A violation forces a decision rather than silent growth.
  4. 4. Why budget third-party scripts separately?

    Third-party code is a common source of regressions, so it needs its own limits and owners.

Summary

  • A budget sets limits on experience metrics, quantities and scores.
  • Derive numbers from RUM data, devices and goals; start achievable and tighten.
  • Enforce with Lighthouse budgets, bundler limits and size-limit in CI.
  • Treat a violation as a decision point: optimize, remove, defer or consciously raise.

Next: Performance in CI and Team Culture