Performance budgets.

Cobbleway sells bike parts at shop.cobbleway.example. Its riders shop from the trail head and the bus stop, so the team designs for a mid-range Android phone on a patchy 4G signal, and it has promised that the main photo on a product page appears within 2.5 seconds for three visits in four. That promise is the requirement. On its own it changes nothing, because no single change ever breaks it: a reviews widget adds a little, a new icon set a little more, and a year later the page takes four seconds and nobody can point at the commit that did it.

A budget fixes that by deciding the limits up front and checking them on every change. The team works out how many bytes fit inside the 2.5 seconds on the phone it designs for, divides those bytes between the parts of the page and the people who own them, and wires a check into continuous integration. A change that would spend more than its share now fails in review, while it is still one diff with one author, instead of surfacing months later as a slow page with a hundred suspects.

The point is not the number itself; it is that the number exists before the feature does. With a budget, adding something heavy becomes a trade the team makes on purpose: shrink something, remove something, or do not ship the new thing in that form.

The three kinds sit in a chain. The quality target is the promise to users, and only field data from real visits can tell you whether you kept it (what each vital means and why p75 is covered in Core Web Vitals as requirements). A milestone timing is the same idea measured on one repeatable lab profile, so it can run before release. A quantity is the cheapest proxy of all: counting the bytes in a build takes seconds and gives the same answer every time, so it can run on every commit.

Each step down the chain is faster to check and further from what users feel. That is why a working budget has more than one kind: quantity limits catch most regressions instantly, timing limits in the lab catch the ones bytes miss (a script that is small but slow to run, a photo requested too late), and the field target tells you whether the lab profile still resembles your users.

To turn a timing into bytes, fix the network you design for and subtract everything that happens before the critical bytes can flow, plus what happens after they arrive. Cobbleway uses Lighthouse's default mobile profile, Slow 4G, as the lab stand-in for its rider on patchy 4G (choosing that profile is the subject of Designing for the device you don't own). At 1.6 megabits a second the pipe moves about 200 KB a second, and every round trip costs 150 ms.

"150 KB of JavaScript" is ambiguous until you say which 150. The window above is about the network, so the budget counts compressed bytes, the ones that cross the wire. But tools disagree on what they count by default, and a limit copied from one tool into another can be off by a factor of three or four, because minified script usually shrinks to a fraction of its size under Brotli. Write the unit next to every limit.

Bytes on the wire are also only the first bill for script. After it arrives, the browser decompresses it, parses and compiles it, and runs it, mostly on the main thread that also handles taps; the V8 team names download and execution as the dominant costs, and a median phone runs the same code several times slower than a high-end one. Why a kilobyte of script costs far more than a kilobyte of photo is taught in Bundle size and what it costs; for a budget the consequence is simple: script gets its own byte limit, and a timing limit on main-thread work backs it up.

A single page-wide number tells you when you are over, not who should fix it. So the total is divided along the lines the code is already divided: the framework runtime every page loads, shared application code (header, basket, search), one chunk per route, and third-party tags. Each slice gets a limit and an owning team, and the slices plus a deliberate headroom add up to the total. A route that loads less shared code may spend more on its own chunk; the total per page is what the network window allows.

Third-party scripts belong inside the budget, not beside it. Analytics, a reviews widget or a chat bubble cross the same pipe and run on the same main thread as your own code; leaving them out makes the budget look healthy while the page is not. Because another company writes them, their slice is usually a count plus a byte ceiling, with marketing or whoever adds them as the owner.

Two checks, at two speeds. The first runs size-limit against the built chunks on every push: no browser, a few seconds, and it names the chunk that grew. The second deploys a preview, loads each key route with Lighthouse CI on the mobile profile several times, and asserts on transfer bytes, the number of third-party requests and the lab timings. Byte checks catch most regressions early and cheaply; the timing check catches what bytes cannot, such as a small script that runs for a long time, or a photo that is now requested late.

Lighthouse 12 removed its own budget.json, so limits that used to live there now go into Lighthouse CI assertions. An error-level assertion makes the run exit non-zero and fails the status check; warn-level ones are printed and let the build through, which is how Cobbleway implements its two levels. How many runs to take, which run an assertion judges, and how to keep a shared runner from producing false alarms belong to Lab data, field data and releases.

A few details make this configuration honest. The size-limit total covers only first-party chunks, because third-party scripts are not in the build; Lighthouse sees them on the loaded page, so the page-wide script total and the third-party requests are asserted there. That count covers every request Lighthouse attributes to a third party, not only script files: Cobbleway's three product-page tags make eight requests between them on a typical load (scripts, a stylesheet, beacons), so the assertion caps eight requests, and checkout's payment SDK makes four. Lighthouse CI wants bytes, so 150 KB becomes 150,000 and 130 KB becomes 130,000. That matches size-limit, which reads "kB" as 1,000 bytes ("KiB" would be 1,024); pick one convention and write it in the file. And the warn level on the overall score is deliberate: a score blends several metrics and moves for reasons nobody can act on, so it informs rather than blocks.