Performance Budget

A performance budget is a set of numerical thresholds applied to chosen performance metrics — such as page weight, LCP, CLS, TBT, or JavaScript bundle size — that triggers an alert or CI build failure when crossed. It is a regression guardrail, not a goal. (web.dev / Google Chrome team; MDN / Mozilla)

---

Budget vs. goal (critical distinction)

Every major practitioner source independently makes the same distinction:

• Goals are aspirational: "How fast do I want this page to eventually be?"
• Budgets are guardrails: "How do I stop this page from getting slower while I work toward that goal?"

"Performance goals are aspirational. Performance budgets are practical. They answer the question 'How can I keep my site from getting slower while I work toward my performance goals?'" (SpeedCurve)

"Most organisations aren't ready for challenges, they're in need of safety nets. Performance budgets should not be things to work toward, they should be things that stop us slipping past a certain point. They shouldn't be aspirational, they should be preventative." (Harry Roberts, CSS Wizardry, 2020-01)

---

What gets budgeted

Three metric categories (web.dev / Google Chrome team, 2018):

Quantity-based metrics — resource sizes and counts:

• JavaScript transfer size (KB, gzipped)
• Image size (KB)
• CSS size (KB)
• Total page weight (KB)
• Number of HTTP requests
• Number of third-party providers/scripts

Milestone timings:

• TTFB (Time to First Byte)
• LCP — Largest Contentful Paint (LCP)
• Interaction to Next Paint (INP) (lab proxy: TBT — Total Blocking Time)
• Cumulative Layout Shift (CLS)
• TTI (Time to Interactive)

Rule-based:

• Lighthouse Performance score

---

How to set a threshold

The practitioner consensus (Harry Roberts, SpeedCurve, Calibre — independently converging) is to derive the starting threshold from real historical data, not an ideal number:

1. Look at the last 2–4 weeks of field or lab data for the target metric on the target page type.
2. Identify the worst data point in that window.
3. Set that worst value as the budget limit. "Take the worst data point in the past two weeks and use that as your limit." (Harry Roberts, CSS Wizardry, 2020-01)
4. Revisit every two weeks. Three possible outcomes per cycle: comfortably under budget (tighten it); nudging the line (maintain vigilance); consistently over (work required). "We can't ever increase a performance budget... We can maintain or decrease one, but we can't increase it." (Harry Roberts)

Google's official guidance uses a different starting point: benchmark 10 competitors, then target 20% faster than the fastest competitor — the 20% rule reflects the minimum speed change users perceive. (web.dev / Google Chrome team, 2018)

Official Google quantity budget (as-of 2018; stale-risk flagged above):

Network	Device	JS	Images	CSS	HTML	Fonts	Total	TTI
Slow 3G	Moto G4	100 KB	30 KB	10 KB	10 KB	20 KB	~170 KB	5 s
Slow 4G	Moto G4	200 KB	50 KB	35 KB	30 KB	30 KB	~345 KB	3 s
WiFi	Desktop	300 KB	250 KB	50 KB	50 KB	100 KB	~750 KB	2 s

(web.dev / Google Chrome team, "Your First Performance Budget", 2018)

---

INP and the lab measurement gap (2024 change)

Interaction to Next Paint (INP) replaced FID (First Input Delay) as a Core Web Vitals metric on March 12, 2024. (Google Chrome team, web.dev/blog/inp-cwv-launch, 2024-03-12)

Critical constraint for performance budgets: INP cannot be measured in lab/synthetic tests — it requires real user interaction. Any FID-based performance budget is now stale. The correct approach (as-of 2026):

• CI/lab budget: TBT (Total Blocking Time) as an INP proxy — "treat a green lab run as necessary but not sufficient" (QASkills, 2026-06-15)
• Field budget: INP from Real User Monitoring (RUM) data, enforced via Chrome User Experience Report (CrUX) or first-party RUM tools
• Synthesis strategy: "Track the metric for synthetic and RUM within the same chart. Create the performance budget for the RUM metric, so you get an alert when the budget is violated... Because you're tracking synthetic data in the same chart, you can easily drill down and get detailed test results and diagnostics." (SpeedCurve)

---

Tooling (as-of 2026-09-08)

Lighthouse CI (@lhci/cli)

The dominant CI integration tool for build-time performance budgets. (Google Chrome team, GoogleChrome/lighthouse-ci, active; v0.15.1 released June 2025)

Two budget mechanisms in lighthouserc.js:

1. Assertions — audit-level thresholds (e.g., 'largest-contentful-paint': ['error', { maxNumericValue: 2500 }], 'categories:performance': ['error', { minScore: 0.9 }]). Three levels: error (fails build), warn (passes with warning), off.
2. budget.json — resource size/count limits by type (scripts, images, fonts, total) in KB.

Common misconfiguration: resourceSizes.budget values are in KB, not bytes. (QASkills, 2026-06-15)

Recommended CI starting budgets for production (practitioner guidance, QASkills, 2026-06-15): Performance score ≥ 0.85, LCP ≤ 2,500ms, CLS ≤ 0.1, TBT ≤ 300ms (warn), Speed Index ≤ 3,400ms (warn). "Begin with realistic thresholds you can actually pass (a gate that is always red gets disabled), then lower them each sprint."

Flakiness mitigation: numberOfRuns: 3 or 5 — Lighthouse CI uses the median run for assertions. (QASkills, 2026-06-15)

Webpack performance hints

Built-in to webpack; warns or errors when bundle size exceeds limit. Default threshold: 250 KB per asset or entry point (uncompressed). (web.dev / Google Chrome team, 2019) Note: webpack compares against uncompressed sizes; bundlesize defaults to gzipped sizes.

Bundlesize (npm)

Enforces asset size budgets in CI pipelines (Travis CI, CircleCI, Wercker, Drone). Tests gzipped sizes by default. Used by Bootstrap, Tinder, Trivago. (web.dev / Google Chrome team, 2019)

Calibre / SpeedCurve

Continuous monitoring platforms for production RUM budgets. Both support automated alerts when field metrics breach thresholds. Calibre offers defensive (current-performance baseline) and aspirational modes. (Calibre blog, 2022; SpeedCurve blog)

Status changes (2024–2026)

• Lighthouse DevTools panel: sunset planned H2 2025 — Lighthouse is NOT deprecated, only moving into the Performance panel (Google Chrome team, developer.chrome.com, 2024-03-14)
• GoogleChrome/budget.json spec repo: archived December 2022 (read-only); LightWallet feature in Lighthouse core remains active (as-of 2026-09-08)
• Web Vitals Chrome extension: standalone support ended January 2025 — integrated into DevTools (Google Chrome team)
• tool.web.dev performance budget calculator: no longer accessible; no formal deprecation notice found (as-of 2026-09-08)
• FID: deprecated March 2024, removed from Chrome tools September 2024 — any FID budgets are stale

---

Minimum Viable Budget strategy

To avoid alert fatigue and stakeholder disengagement, SpeedCurve recommends Minimum Viable Budgets for teams new to the discipline: start with one or two metrics, confirm the mechanics work, teach stakeholders why those metrics matter, then add more. "A budget threshold set too ambitiously becomes demoralizing, not actionable, and ignorable. Because you've already violated your budget, you won't get alerts if performance degrades even further." (SpeedCurve)

Recommended starting metrics (Calibre, 2022): Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), and TBT — "because they improve the user experience, boost web performance, and are a direct ranking factor for Google."

---

Ecommerce application

Page priority ranking

SpeedCurve recommends applying budgets to pages in order of conversion impact, not traffic: (1) Product detail page (PDP), (2) Product category/listing page, (3) Shopping cart, (4) Homepage. Budgets on the homepage alone miss the pages where most revenue is lost. (SpeedCurve, "A Retailer's Guide to Web Performance")

Four dominant performance problems on retail sites

Third-party scripts (typical retail page carries upwards of 75 third-party scripts), stylesheets (CSS blocking render), custom fonts, and page size especially images. (SpeedCurve, "A Retailer's Guide to Web Performance")

CLS in ecommerce — underappreciated

Cumulative Layout Shift (CLS) is repeatedly flagged as the most underappreciated budget metric in ecommerce specifically: layout shifts on product pages during size/colour variant selection, sticky header collapse on scroll, and late-loading third-party overlays directly cause accidental taps that show up as bounces. "Sessions experiencing high CLS (above 0.25) had a 67% bounce rate on product pages, compared to 38% for sessions with low CLS." (WebVitals.tools case study, 2026-05-12)

Case study: Shopify Plus fashion brand (as-of 2026-05-12)

Source: WebVitals.tools / Sarah Martinez. Subject: unnamed $28M-revenue Shopify Plus fashion brand, 72% mobile traffic, 8,500 product pages.

Baseline (mobile, p75 field): Homepage LCP 5.2s / CLS 0.32 / INP 340ms; PDP LCP 4.1s / CLS 0.28 / INP 290ms — all "Poor."

Root causes identified: 23 Shopify apps injecting 1.2 MB of JS; unoptimized JPEGs served at full resolution; 450 KB of CSS (38% used on any page); no font-display: swap; variant selectors causing layout reshuffles.

Conversion rate by LCP bucket (pre-optimisation, mobile): Fast (<2.5s) = 2.8%; Moderate (2.5–4s) = 1.6%; Slow (>4s) = 0.7%. "Sessions with fast LCP converted at four times the rate of slow LCP sessions."

After 12 weeks: Homepage LCP 2.1s / CLS 0.06 / INP 160ms; PDP LCP 1.6s / CLS 0.04 / INP 140ms — all "Good." CWV pass rate in Search Console: 11% → 96%.

Business results (90 days, mobile): Conversion rate +17% (1.4% → 1.64%); bounce rate -24% (58% → 44%); annualized mobile revenue +$1.2M on $28M base; organic traffic +31%.

App audit finding: 10 of 23 Shopify apps were unused or redundant. Removing them cut JS from 1.2 MB to 340 KB (as-of 2026-05-12).

Project economics: $35,000 project cost; $1.2M annualized revenue increase = 34× ROI (as-of 2026-05-12).

Practitioner lesson recorded in source: "Without guardrails, new apps, campaigns, and design changes will erode your gains within months." — reinforcing the budget-as-guardrail argument. (WebVitals.tools, 2026-05-12)

---

Key terms

Term	Meaning
Performance budget	Threshold applied to a metric that triggers an alert or CI failure when crossed
LightWallet	Lighthouse's built-in budget enforcement feature (active; accessible via --budget-path CLI flag)
budget.json	Configuration file defining resourceSizes and resourceCounts limits for LightWallet
TBT (Total Blocking Time)	Lab-measurable proxy metric for INP; the only way to enforce INP-related budgets in CI
Minimum Viable Budget	Strategy to start with 1–2 metrics to build team familiarity before expanding
Defensive budget	Set at current worst performance; blocks regression
Aspirational budget	Set at target performance; tracks progress toward a goal
20% rule	Users reliably perceive speed differences of ≥20%; recommended competitive gap to target

---

Next frontier concepts (dangling links)

TTFB · Partial Prerendering · Soft Navigations · Total Blocking Time (TBT) · LightWallet · Performance Monitoring