Performance Budget: Definition and Examples

What is a performance budget?

A performance budget is a set of limits on metrics that affect site speed, such as script size, number of requests, page weight or load timings. The team agrees on the limits up front and treats them like any other requirement: a change that pushes the page over a limit gets fixed or the limit is changed on purpose. It turns "make it faster" into a number you can check on every release.

Why budgets matter

Pages rarely get slow in one step. Each change adds a little script, an image or a tag, and no single change looks guilty. A budget makes the cost visible at the moment of the change, when it is cheapest to fix.

Types of performance budgets

• Quantity-based. Counts and sizes: JavaScript in kilobytes, number of requests, number of web fonts, third-party resources.
• Milestone timings. Moments in the load such as First Contentful Paint or Time to Interactive, plus user-centric metrics: Largest Contentful Paint, Interaction to Next Paint and Cumulative Layout Shift.
• Rule-based. A minimum Lighthouse score or a rule such as no render-blocking scripts.

web.dev recommends combining quantity-based limits with user-centric metrics. Size limits are easy to enforce on every build, while timings describe what users feel.

Example

Lighthouse reads a budget file and reports against it:

# budget.json
[
  {
    "path": "/*",
    "timings": [{ "metric": "interactive", "budget": 3000 }],
    "resourceSizes": [
      { "resourceType": "script", "budget": 125 },
      { "resourceType": "total", "budget": 300 }
    ],
    "resourceCounts": [{ "resourceType": "third-party", "budget": 10 }]
  }
]

lighthouse https://example.com --budget-path=./budget.json

This example limits Time to Interactive to 3000 ms, JavaScript to 125 KB, total page weight to 300 KB and third-party requests to 10. Units are milliseconds for timings and kilobytes for sizes. Pick numbers from your own measurements, not from an example.

Choosing the numbers

1. Measure three to five representative pages on a throttled mobile profile.
2. Set each limit at or slightly below today's value, so the first run passes and any slip fails.
3. Use the Core Web Vitals "good" thresholds as targets for the timing metrics: LCP of 2.5 seconds or less, INP of 200 milliseconds or less, CLS of 0.1 or less, assessed at the 75th percentile of page loads (web.dev). See Core Web Vitals.
4. Set separate budgets per page type. A marketing page and a dashboard have different needs.
5. Review the limits on a schedule and tighten them as the site improves.

For a starting point on size, web.dev's own baseline is under 5 seconds Time to Interactive and under 170 KB of critical-path resources on a slow mobile network, which you should treat as a default to beat, not a goal. Images are usually the heaviest item, so see image size first.

How to enforce a budget

• In the build. Run Lighthouse with a budget file, a bundle size check or a tool such as Lighthouse CI so a pull request fails when it exceeds a limit.
• In production. A build check only sees the code. Scheduled audits of the live site catch regressions from third-party tags, content changes and infrastructure. LoadFocus page speed monitoring runs scheduled Lighthouse audits from 25 cloud regions, lets you set Core Web Vitals budgets and alerts by email, Slack or Microsoft Teams when a score or metric crosses your threshold. For a one-off look, use the Core Web Vitals checker.

Use both: the build check stops a regression before it ships, and the scheduled audit tells you when production drifts. The blog guide how to set performance budgets for web apps goes deeper on rollout.

Common mistakes

• Budgets set so tight that every change fails. The team then turns the check off.
• Warnings nobody acts on. A budget that does not block or page someone is only a suggestion.
• Judging one noisy run. Lab results vary between runs, so compare several runs or look at trends.
• Lab only. A page can pass in the lab and still be slow for real users. Pair budgets with field data.
• Forgetting third-party scripts. Tags added by marketing often use most of the budget. Give them their own limit.
• One budget for the whole site. Critical flows such as checkout and signup need their own limits.
• No owner. Someone has to defend each limit and approve a raise.

FAQ: Performance budget

What should a first budget look like?

Start from your measured baseline for a few key pages, set limits at or just below it, and add the Core Web Vitals thresholds as timing targets. Tighten later.

How is a performance budget different from Core Web Vitals?

Core Web Vitals are the metrics. A performance budget is your team's agreed limit on those metrics and on things like script size and request count.

Should budgets use lab or field data?

Both. Lab tools such as Lighthouse suit build checks because they are repeatable. Field data shows what real users experience.

What if a change goes over budget for a good reason?

Either optimize until it fits or raise the limit on purpose, with the team's agreement and a note why. Do not bypass the check quietly.

How often should I review the budget?

On a regular schedule, for example every quarter. Tighten limits that always pass and investigate limits that fail often.