We once shipped a launch screen with a hero animation that added about as much weight as the rest of the mini-program combined. Nobody objected, because there was nothing to object to — no number written down anywhere said it was too much. The review was about whether the animation looked good. It did. It also made the first screen feel slow on the phones most of our users carry.

A performance budget is just a number the team agrees not to cross, decided before the work starts. That's the whole idea, and it's the part people skip: they promise to optimise after launch, which is a promise nobody ever collects. We've stopped making it.

Pick numbers you can defend

Don't copy thresholds from somebody else's blog. The package ceiling comes from the host's own limits plus the slowest network you're willing to support; the first-screen target gets measured on the cheapest phone you can find, not on a laptop. Set it too loose and it doesn't exist; set it too tight and people start looking for ways around it. We've seen both. What we do now is write next to every number where it came from: which device, which network, which measurement. Six months later, when someone argues with the line, at least the argument has evidence.

The other thing people miss is that a budget isn't one line, it's a set. Package size, first screen ready, requests fired on a cold start, long tasks on the main thread, peak memory, and how much each third-party SDK is allowed to weigh — none of these cancels another. A page can keep the bundle beautifully small and still feel slow because it added six serial startup calls.

Budget itemHow to set the thresholdHow CI enforces itThe usual excuse
Package sizeHost limits plus the slowest supported networkFail the build over a hard cap, warn on driftOne more icon set, that's all
First screen readyMeasure on the cheapest phone, not a laptopCompare against a stored baseline on every PRThe designer signed off on this version
Requests on a cold startCount what a cold start actually firesReject a PR that adds an unconditional startup callWe'll batch it in the next sprint
Long tasks on the main threadSample a real device, pick a ceiling you can hitBlock merges when a recorded trace crosses itJust a small animation
Peak memoryHighest reading across the device matrix, with headroomGate on a slow-device profile run nightlyOnly flagship phones crash anyway
Third-party SDK weightBudget per dependency, not one global totalFail when a new dependency lands without an ownerMarketing needs it for the campaign

What the budget will cost you

Let's admit first that it gets in the way. Some features are genuinely worth building and genuinely push the first screen over the line, and there's no clever trick that satisfies both sides — somebody has to decide. We tried keeping the budget as a soft warning; within three months every warning was being ignored and the line had quietly ceased to exist. We moved to a hard block, and the price is a meeting every few weeks about whether to loosen it temporarily for a campaign. That's annoying, but usefully annoying: it drags the argument out of the night before launch and into daylight, with a record.

Business asking for exceptions is normal, and pretending otherwise is dishonest. Our rule isn't that you can't break the budget. It's that breaking it leaves a name and an expiry date: who approved it, how far it was loosened, and when it comes back. An exception without an expiry date is a permanent raise in disguise.

The sneakier problem is that the baseline moves under you. A host upgrades its base library, changes compression, rewrites its startup path, and overnight a line you measured carefully is all red or all green. So after every major host version we re-measure the baseline rather than reading the difference as the team getting better or worse. Blaming engineers for a platform change is the fastest way to make everyone stop trusting the budget.

Put the gate in the pipeline, with a name on the exception

We built these checks into the Cross Mini App pipeline, but the rule that actually works isn't a technical one: an exception needs a named owner and an expiry date. Tooling can report the number. It can't decide for you whether the number or the campaign wins this sprint.

Now a PR with a new feature runs the budget alongside the tests. Go over and it goes red, and red with reasons: which device, which number, how far above the baseline. Want to merge? Come with an argument and a date to give the headroom back. It's a little slower than we'll optimise after launch, and a lot more honest — mostly because we never once collected on that promise.

Sources

  • web.dev Learn — the grounding for core metrics and what to measure first.
  • MDN — Performance — long tasks, memory and other signals you can actually gate on.
  • HTTP Archive — real-world distributions to set a baseline against, instead of a guess.
  • Think with Google — why speed turns into a business argument, not just an engineering preference.