Writing a Performance Budget That Fails Builds

A performance budget is only useful if it fails the build at the right moment: not on every pull request because the numbers were aspirational, and not never because they were so loose nothing could cross them. Getting there means deriving numbers from your own site, setting them per template, choosing which limits are hard errors and which are warnings, and tightening them on a schedule rather than in a burst of enthusiasm.

This guide builds a budget for a Hugo marketing and documentation site with four templates, encodes it for Lighthouse CI, and shows six months of how it behaved. It builds on the concepts in Performance Budgets and Lighthouse CI and assumes the wiring from Setting Up Lighthouse CI for a Static Site.

Prerequisites

• Lighthouse CI running against preview deploys, or at least locally against the built site.
• A list of your templates and one representative URL for each.
• Field data for context if you have it — CrUX or your own real-user monitoring.

Step 1: Measure Where You Are

Run Lighthouse five times against each template's representative URL on the same infrastructure CI will use, and record the medians. Resource sizes come from the resource-summary audit; timings from the metrics.

for url in / /pricing/ /docs/getting-started/ /blog/2026/launch/; do
  npx -y @lhci/cli@0.14.x collect --url="$PREVIEW$url" --numberOfRuns=5 >/dev/null
done
npx -y @lhci/cli@0.14.x assert --preset=lighthouse:no-pwa --no-lighthouserc > baseline.txt || true
node scripts/lhci-medians.mjs .lighthouseci > baseline.json

The baseline for the four templates:

The table already argues against a single site-wide budget. A 70 KB script limit is tight for pricing and four times too loose for docs, where an accidental 40 KB dependency would pass unnoticed.

Step 2: Set Limits per Template

For each template and metric, set the warning at today's value rounded up, and the error roughly 10–15% above it for bytes and 20% above it for timings, which vary more. Where today's value is already above a sensible absolute limit — say, LCP above 2.5 s — set the error at the absolute limit and plan the fix.

Lighthouse's native budget.json expresses byte and count limits per path:

[
  {
    "path": "/docs/*",
    "resourceSizes": [
      { "resourceType": "script", "budget": 25 },
      { "resourceType": "stylesheet", "budget": 26 },
      { "resourceType": "font", "budget": 55 },
      { "resourceType": "image", "budget": 40 },
      { "resourceType": "total", "budget": 150 }
    ],
    "resourceCounts": [{ "resourceType": "total", "budget": 15 }],
    "timings": [
      { "metric": "largest-contentful-paint", "budget": 1500 },
      { "metric": "total-blocking-time", "budget": 60 }
    ]
  },
  {
    "path": "/blog/*",
    "resourceSizes": [
      { "resourceType": "script", "budget": 30 },
      { "resourceType": "image", "budget": 180 },
      { "resourceType": "total", "budget": 330 }
    ],
    "timings": [{ "metric": "largest-contentful-paint", "budget": 2300 }]
  }
]

Sizes are in kilobytes of transfer size and timings in milliseconds. Paths match with a trailing wildcard, and the first matching entry wins, so list specific paths before general ones.

Step 3: Decide Error Versus Warning

Not every limit should block a merge. The rule that worked here:

• Errors: byte and request budgets (deterministic, so a failure is always real), CLS (small spread in practice), and rule audits such as unsized-images and font-display.
• Warnings initially, errors later: LCP and TBT. After four weeks of results, compute each metric's spread across unchanged builds; once the error threshold sits more than two spreads above the median, promote it to an error.

In Lighthouse CI this becomes a combination of budgetsFile and explicit assertions:

// lighthouserc.js (assert section)
assert: {
  budgetsFile: './budget.json',        // byte/count limits → errors
  assertions: {
    'performance-budget': 'error',
    'timing-budget': 'warn',           // promote after four weeks
    'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
    'unsized-images': 'error',
    'font-display': 'error',
  },
},

Step 4: Ratchet Down Each Quarter

A budget that only ever rises is a record of decline. Every quarter, compare each limit with the template's actual values over the period. Where a template stayed well under its limit the whole time — more than 15% headroom — lower the limit to the new reality plus the usual margin. A short script reads the stored Lighthouse CI results and prints proposed new limits; a human reviews and commits them.

Proposed budget changes (Q3)
  /docs/*   script   25 → 22 KB   (max seen 19.4)
  /docs/*   LCP      1500 → 1400 ms (p95 of medians 1.26 s)
  /blog/*   image    180 → 160 KB (max seen 138)
  /         (no change — within 8% of limits)

Ratcheting is what turns one-off optimisation work into a permanent gain. Without it, the next regression can quietly consume the headroom the optimisation created.

The ratchet also changes how optimisation work is valued. When a developer trims 3 KB from the docs template, the next quarterly review turns that saving into a lower limit, so the gain is protected rather than silently spent by the next feature.

Measured Impact

Six months on the four-template Hugo site:

No byte-budget error in six months was a false alarm, which is the property that kept the team trusting the check.

Common Budget Mistakes

Four mistakes account for most budgets that get abandoned. Aspirational numbers: setting the docs LCP limit to 1.0 s because it sounds good, when today's median is 1.2 s, produces a check that fails on every pull request until someone disables it. Counting the wrong bytes: resourceSizes are transfer sizes, so a budget copied from a tool that reports uncompressed sizes will be roughly three times too loose for text assets. Forgetting third parties: scripts loaded from other origins count towards the page's totals, and a vendor update can push a template over its limit without any change in your repository; a nightly run against production, as described in Auditing Third-Party Scripts with Lighthouse, catches those. No owner: someone must review warnings weekly and run the quarterly ratchet, or both quietly stop.

Pitfalls & Rollback

• Wildcard order. budget.json uses the first matching path. Put /docs/api/* before /docs/*, or the API pages inherit the wrong limits.
• Budgets on uncompressed sizes. Lighthouse measures transfer size. Compare like with like when copying numbers from bundler output.
• Raising limits silently. Require a reason in the commit message and approval from the budget owner for any increase.
• Ignoring warnings forever. A warning nobody reads is noise. Review them weekly, or delete the ones that never lead to action.
• Rollback: the budget is two files. Reverting a limit change is a one-line diff; demoting an assertion from error to warn makes it advisory without removing the data.

Conclusion

A performance budget that fails builds usefully is built from your own numbers, set per template, split into deterministic errors and measured-noise warnings, and ratcheted down every quarter. On this four-template site that produced 29 build failures in six months, every one a real regression, and a field LCP that improved from 2.0 to 1.7 seconds instead of drifting the other way.

FAQ

Where should the first budget numbers come from?

From your own site's current measurements, plus a small margin. Measure each template with the median of several Lighthouse runs, set the error threshold about 10 percent above today's value and the warning threshold at today's value, then tighten as you fix things.

Should every template share one budget?

No. A homepage with a hero image and a text-only reference page have different realistic limits. Use per-path budgets so each template is held to a limit it can actually meet, and one heavy template cannot hide regressions in light ones.

What is the difference between budget.json and Lighthouse CI assertions?

budget.json is Lighthouse's native format for resource sizes, request counts and timings per path. Lighthouse CI assertions can check those budgets and any other audit or metric. Many teams use budget.json for bytes and assertions for metrics and rules.

How often should budgets be tightened?

Quarterly works well. Review the headroom each template has against its limits, and lower any limit where the template has sat comfortably below it for the whole quarter.

Related

• Parent: Performance Budgets and Lighthouse CI — the overall approach.
• Setting Up Lighthouse CI for a Static Site — the pipeline these budgets plug into.
• Reducing Lighthouse Score Variance in CI — shrinking the spread before promoting timings.
• Tracking Bundle Size per Pull Request — byte budgets enforced at build time.
• Comparing Lab and Field Data with CrUX — checking the budget protects real readers.