Performance Budget in CI: Stop Regressions Automatically

Performance is not a property you establish once and that then stays. It is a state that is at stake again with every code change. The tricky thing about performance regressions is that they happen gradually and produce no visible error: the page still works, it just loads a bit slower, responds a bit more sluggishly, or briefly shifts the layout while building up. For the person who checked in the change, everything looks fine on a fast office machine with a stable network. Only the real users on mid-range smartphones on mobile networks feel the degradation – and they show up in no bug report; they simply leave.

The economic consequences are well documented. Just 0.1 seconds (Deloitte) of faster load time raised retail conversions by 8.4 percent (Deloitte) in a cross-industry analysis. Conversely, the probability that a user leaves the page again rises by 32 percent (Google/SOASTA) when load time grows from one to three seconds. And the conversion rate drops, according to an analysis of millions of page views, by about 4.4 percent (Portent) with every additional second in the first five seconds. Every unnoticed regression therefore costs measurable money. The classic reflex remedy – a big performance audit every few months – comes too late for these small, continuous degradations: by the next audit, dozens of mini-regressions have accumulated, and nobody knows anymore which change contributed what.

A performance budget flips the logic. Instead of hunting for degradations after the fact, it prevents them at the source. It makes performance a condition every change must meet before it may enter the main branch – the way automated tests ensure a change does not break an existing function. Anyone who wants to understand the three Core Web Vitals in context will find the classification in the article on Core Web Vitals 2026; here it is about how to enforce their compliance permanently.

The heart of it is a plain text file called budget.json. In a clearly readable format it describes which upper limits apply – separated into time metrics (timings) and resource quantities (resourceSizes and resourceCounts). Each rule refers to a path, so different page types can be treated differently. The file lives in the repository next to the code and is thus versioned itself: every change to the budget is traceable, and the budget goes through the same reviews as the rest of the project.

In this example, LCP may be at most 2,500 milliseconds, Total Blocking Time at most 200 milliseconds, and the delivered JavaScript at most 400 kilobytes. Lighthouse reads this file, compares the measured values with the budgets and flags every item above the limit as over budget. That alone, however, does not yet stop a build – it only produces a report. To turn the report into a real gate, a second building block is needed: Lighthouse CI.

A budget is only as useful as its thresholds. If they are too loose, regressions slip through and the gate lulls you into false security. If they are too strict or too close to the current measurement, the build fails on normal measurement noise – and a team that constantly sees red runs without a real reason gets used to ignoring them. A good budget therefore starts at the official target values and leaves a small, deliberate buffer. The median of several runs and a warning level below the hard error limit help separate the noise from genuine degradations.

It is also important to differentiate the budget per page type. The home page, a category page, a product page and a blog article have completely different realities: what is generous for a text-heavy article page would be unrealistically tight for an image-heavy product page. That is why budget.json allows different rules per path. A frequent trigger for exceeded budgets are third-party scripts that creep in unnoticed via tag managers; how to reduce that load deliberately is covered in the article on trimming third-party scripts.

As effective as a CI budget is – it measures in the lab, not with real users. The lab delivers reproducible values under controlled conditions and is therefore ideal for detecting regressions between two states. What real people experience on their devices and networks, however, only field data shows. And the difference is economically relevant: if load time grows from one to five seconds, the bounce probability rises by 90 percent (Google/SOASTA), and in the travel segment, just 0.1 seconds of faster loading brought 10.1 percent (Deloitte) more conversions. These effects arise in the field, not in the lab.

That is why the lab budget and field measurement belong together: the budget in CI prevents a regression from ever going live; the field measurement confirms that the values hold with real users too. How lab and field data – that is, Lighthouse runs, RUM and Google's CrUX data – sensibly combine into an overall strategy is explored in the article on RUM, CrUX and performance budgets. And because INP can only be approximated in the lab via TBT, a complementary look at INP optimization in detail is worthwhile.

This is exactly how we proceed when setting it up: we identify the critical page types, calibrate realistic budgets for LCP, INP and CLS, anchor Lighthouse CI as a required check in your pipeline and support the team until red runs are understood as a helpful signal rather than a nuisance. Which services this includes is shown in our overview of performance services; for the concrete frontend levers with which an exceeded budget can be reeled back in, our frontend optimization helps.