What a performancebudget actually buysyou

A performance budget is not a score to chase. It is a number agreed before the work starts, so that the conversation about whether to add something happens while it is still a question.

Without one, every individual addition is reasonable. One more font weight is reasonable. One more analytics script is reasonable. A chat widget is reasonable. Nobody ever adds the thing that breaks the page; the page is broken by nine reasonable additions and no agreed limit.

The budget's real function is procedural. It turns "should we add this" from a matter of taste into a matter of arithmetic, which is a much shorter conversation.

The first time I was asked to make a page faster I went looking at the animations, because those were the visible, expensive-feeling things. They were not the problem. The problem was a video that downloaded on every visit before anybody had scrolled, an image served at four times the size it was drawn at, and a third-party script loaded in the root layout for a widget that appeared on one page.

That pattern has repeated on every project since. The expensive things are rarely the ones that look expensive. They are the ones nobody chose — a default, an import that pulled a library in, a component re-exported from a shared file.

Which means the honest order of work is: measure, find the thing nobody decided, fix that. Only if the budget still cannot be met is there a design conversation, and that conversation belongs to the designer, not to me.

The lesson that cost me the most time: an element that is hidden with CSS has still been downloaded. A video rendered twice — one for mobile, one for desktop, each hidden at the other breakpoint — downloads both. So does a hidden image, and so does a hidden iframe.

The browser does not know the design intent behind a display rule. If the element is in the document with a source attached, the source is fetched.

The fixes are all structural rather than visual. One element whose source swaps, or a <source media="...">, or a component that only mounts when the viewport actually calls for it. The design is identical at both sizes; the page simply stops downloading the half it is not showing.

This one is specific and it generalises. A project with a single file that re-exports every component is convenient right up until something heavy lands in it. After that, every file importing that barrel for one small helper drags the entire module graph behind it — a slider library, an animation plugin, a chart package — into routes that render none of them.

The symptom is confusing: a route gets slower and nothing on that route changed. The cause is in a file it only touched for a utility function.

The rule we settled on is that heavy components are never re-exported from the shared barrel. They get imported from their own path at the one place that uses them. It is marginally less tidy and it is the difference between a shared chunk that is small and one that is not.

The largest thing on screen when the page first paints is a single element, usually an image, and it gets different treatment from everything else: a high priority, a correct size hint, no lazy loading.

Everything below the fold gets the opposite. Lazy, no priority, and a size hint that reflects the width it is genuinely drawn at rather than the width of the file. A hero image sized for a desktop header, served to a phone at the same dimensions, is the single most common waste I have found in an existing codebase — and it is invisible, because the page looks correct.

The other half is format. Modern formats are meaningfully smaller at the same visual quality, and a framework image component will serve them and fall back automatically. Doing that is free. Not doing it is a choice to send more bytes for the same picture.

Transform and opacity are composited. Width, height, top, left, and most filters are not — changing them forces the browser to recalculate layout, and doing that inside a scroll handler produces exactly the stutter the animation was supposed to avoid.

The same applies to reading layout. Asking an element for its position or size inside a scroll or resize handler forces a synchronous layout calculation, and doing it on every event rather than once per frame is how a smooth design ends up feeling cheap on a mid-range phone.

The fix is unglamorous: batch the reads into one animation frame, write only transforms and opacity, and let the compositor do its job. The animation looks the same. It just stops costing anything.

Every embed, widget, tag manager and chat bubble is code you did not write, loaded at a time you did not choose, in a size that can change without warning. Mounting one in the root layout means every route pays for it, including the routes it is irrelevant to.

Mount it on the page that needs it. Load it after the page is interactive at the earliest. Where it can wait for a click or for the section to scroll into view, make it wait — a booking widget that loads when somebody scrolls to the booking section is indistinguishable, from the user's side, from one that loaded at the start.

And check the size again after a few months. It will have grown.

The last lesson is about honesty. Numbers from a desktop machine on fast broadband are not the numbers your visitors get, and a single run is noise. We measure on the mobile preset, more than once, and report what came back rather than the best of five.

A performance claim without a number attached is not a claim. It is a feeling about a page, and feelings about pages are the reason the original problem existed.