# Performance Budget

A performance budget sets explicit limits on measurable performance indicators or resource costs so teams can control regressions during delivery.

- Type: artifact
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-10-19
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/performance-budget/>)

## What it means

A performance budget is an agreed set of thresholds for a defined page, workflow, or product surface under stated test conditions. It can cover user-facing timings, transferred bytes, JavaScript size, or request counts. Resource limits are useful leading checks, but staying below a bundle-size limit does not by itself guarantee fast interactions.

## Why it matters

Individual features often add small costs that accumulate. A budget makes tradeoffs visible during design and delivery rather than waiting for a slow product to become a large remediation project.

## When to use it

Use budgets for important user journeys and resource-constrained devices or networks. Set thresholds from user needs and measured baselines. Avoid adopting another product’s numbers without matching its audience, hardware, network conditions, and tasks.

## How it works

1. Select important surfaces and representative measurement conditions.
2. Choose a small set of outcome timings and supporting resource limits.
3. Establish thresholds, owners, and how exceptions are reviewed.
4. Automate repeatable checks and complement them with field measurements.
5. Investigate breaches and trade off additions against removals or optimizations.

## A practical example

A product team sets an illustrative 180 KB compressed JavaScript budget for its public signup route. A chart library pushes the route beyond it. The team loads the chart only after signup and checks actual interaction timing as well as bundle size.

## Where it breaks

Lab measurements can be noisy and do not represent every user. Byte limits miss execution cost, and a performance score can hide individual regressions. Budgets can become meaningless if every breach is waived or if thresholds are never revisited.

## Common mistakes

- Using a resource-size limit as proof of good user experience.
- Running incomparable tests on changing devices or networks.
- Defining thresholds without ownership or a response to violations.

## Sources

1. [Performance budgets 101](<https://web.dev/articles/performance-budgets-101>) — Google web.dev · Technical guidance
2. [Performance budgets](<https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Performance_budgets>) — MDN Web Docs · Official documentation

## Related topics

- [Non-Functional Requirements](<https://wiki.soroush.uk/topic/non-functional-requirements/>)
- [Code Splitting](<https://wiki.soroush.uk/topic/code-splitting/>)
- [Lazy Loading](<https://wiki.soroush.uk/topic/lazy-loading/>)
