Performance budget — what it is and why care

A performance budget sets hard limits on page weight and speed metrics. Without one, pages tend to get heavier with every release, and nobody notices until it hurts.

Performance budget — what it is and why care

Nobody decides to make a website slow. It happens one reasonable change at a time: a chat widget, another analytics tag, a slider library for one page, a bigger hero image because the old one looked soft on new screens. Each addition is small. Months later they add up to a page that takes noticeably longer to load on a phone, and nobody can say when it happened.

A performance budget is the guardrail against that drift. It's a set of hard limits on page weight, third-party scripts and speed metrics, agreed once and checked automatically on every change.

Performance budget — what it is and why care
Performance budget tracker — anything past 100% triggers a CI fail.

What goes into a budget

Budgets come in three kinds, and a useful one mixes them:

  • Quantity limits: total JavaScript, CSS and image weight, number of requests, number of third-party domains.
  • Timing metrics: Largest Contentful Paint, Interaction to Next Paint, Cumulative Layout Shift, or lab metrics such as Total Blocking Time.
  • Score thresholds: a minimum Lighthouse performance score. Handy as a summary, but it shouldn't be the only check, because a single score hides which part got worse.

A starting point for a content site

The numbers below are an example, not a standard. They suit a typical marketing or corporate site; a web application will need its own.

  • Initial HTML: around 50 KB
  • JavaScript: around 200 KB compressed, in total
  • CSS: around 50 KB compressed
  • Images above the fold: around 300 KB
  • LCP 2.5 s or less, INP 200 ms or less, CLS 0.1 or less (Google's "good" thresholds)

A better way to set yours: measure where the site is today, then set the limits slightly below the current state for the metrics that matter, so the trend points downward. Check two or three competitors as well. Being noticeably slower than the alternatives is what users actually feel.

How to enforce it

A budget that lives in a document is forgotten within a month. It has to fail something. Common tools:

  • Lighthouse CI runs Lighthouse on every pull request and can fail the build when metrics or resource sizes cross your assertions.
  • bundlewatch or size-limit check JavaScript bundle sizes in npm-based projects.
  • webpack-bundle-analyzer and similar tools show what's inside a bundle when a check fails, so you can find the dependency responsible.
  • Real-user monitoring, such as the Chrome UX Report, the Core Web Vitals report in Search Console, or the web-vitals library sending data to your own analytics, shows whether lab improvements actually reach visitors.

A minimal Lighthouse CI configuration with a few assertions might look like this:

{
  "ci": {
    "assert": {
      "assertions": {
        "largest-contentful-paint": ["error", {"maxNumericValue": 2500}],
        "cumulative-layout-shift": ["error", {"maxNumericValue": 0.1}],
        "resource-summary:script:size": ["error", {"maxNumericValue": 200000}]
      }
    }
  }
}

What it changes in practice

Without a budget the arithmetic is quiet but relentless. If every few pull requests add a few kilobytes, a year later the page carries a lot of weight nobody consciously approved. With a budget, a failing check forces a conversation. Do we need this library, or can we drop another one? Can this widget load after the main content? That conversation is the whole point.

Common mistakes

  • Setting limits so loose they never fail, or so tight they fail on every change and get switched off.
  • Measuring only on a fast office laptop. Test with mobile CPU and network throttling.
  • Forgetting third-party scripts. Tag managers let marketing add scripts without code review, so include them in the budget.
  • Treating performance as a developer-only concern. Designers and marketers make choices that affect it too.

To understand the metrics themselves, read how to measure Core Web Vitals. If your site has already drifted, our website audit shows what's slowing it down, and ongoing technical support can keep the budget enforced after the fix.

Want help setting a budget for your site? Message us on Telegram or MAX.

Website development
Related service — let's discuss your project.

Got a project on this topic? Tell us the task — we'll come back with an estimate and a schedule.

Message on Telegram → Message on MAX