AngoraTek FR
← Back to Blog
Methods 7 min read

A Performance Budget Is a Team Agreement. CI Is How You Keep It.

The review lasted forty minutes and produced no decision. A 214 KB date-range picker had landed in a pull request, the reviewer asked whether the product needed it, the author answered that it tree-shakes, and both of them were describing the file differently without a number between them. Two engineers, one dependency, and nowhere to put the argument.

The budget is where the argument goes, and the config file is the small half of that work. Our position: a performance budget is a document about what users should be able to do on each route and on which device. The CI check exists only to record the agreement the team already reached. Teams that start from a web.dev page of recommended numbers and skip the meeting get a red pipeline people route around, which is worse than no budget, because red means nothing after the third Tuesday in a row. Decide first, then enforce.

Budget the route, not the codebase

The first decision predates any tooling: one number per route, because routes are the unit a user actually loads. A pricing page, a map editor, and a checkout flow do not carry the same content, so they cannot carry one ceiling without the ceiling becoming wrong for all of them. Set two budgets in your first hour: the strictest number you can defend for landing routes, where strangers decide whether to trust you, and a looser number for app routes, where a signed-in user has already paid the cost of the session.

The map editor's budget being three times the pricing page's is not a scandal. It is the agreement, written down. What is scandalous is discovering it in a review, route by route, a hundred times a year.

The file itself lives beside the routing table, reviewed with the same diff as the code, and a budget change is a pull request with a sentence of reasoning attached. That last touch sounds ceremonial and is not. A budget edited without a sentence gets edited again for convenience, and the third edit nobody remembers is how budgets die. One reviewer in three can veto a loosened route number; that veto is the entire governance model, and it fits in a paragraph.

{
  "budgets": [
    {
      "path": "/pricing",
      "resourceSizes": [
        { "resourceType": "script", "budget": 90 }
      ],
      "timings": [
        { "metric": "largest-contentful-paint", "budget": 2500 }
      ]
    },
    {
      "path": "/app/map",
      "resourceSizes": [
        { "resourceType": "script", "budget": 280 }
      ]
    }
  ]
}

The shape above is Lighthouse CI's budgets format: script kilobytes per route, plus a timing where the route deserves one. Save it as budget.json and point ci.assert.budgetsFile at it. The values are placeholders for your own decision. A 2,500 ms LCP number on the landing route is Google's published Good threshold; it exists to be argued downward, and the argument is the point.

Measure on the phone, not on the workstation

A budget someone set on a developer's machine is a budget for a laptop on a fast connection with a full cache, which is a device nobody's customer owns. The honest setup tests on a mid-tier Android over throttled 4G, with the cache cold, because that is the configuration your new visitor arrives in. Chrome DevTools does this in its Performance panel. The first time you throttle to 4G fast and watch the picker's 214 KB parse, the argument about whether it tree-shakes ends, because a minified but unsplit bundle ships whole and the phone pays for every byte whether or not a bundler could in principle have removed some.

That run belongs in the meeting where the budgets are set, not just in CI afterward. People negotiate with numbers they have watched happen. Nobody defends a 280 KB app-route budget to a colleague who has just watched it crawl on the bus.

The check that records the agreement

Enforcement comes third, and it is the boring half, which is how you know the hard part was the agreement. Two public tools carry most of it. Lighthouse CI reads the budgets file above and fails the run when a route exceeds it. size-limit fails a pull request when an entry point crosses its number, which makes it the right tool for the app-route case, where bundle diffing matters more than a full audit.

The third tool is a comment, not a gate. Run source-map-explorer in CI on the bundle for the route that changed and paste the module-level breakdown into the pull request. The reviewer stops arguing tree-shaking and starts reading a list of packages with byte counts next to them. Enforcement works because it moves the argument from adjectives to arithmetic.

How 214 KB becomes zero

The dependency argument has three questions, and answering them is the whole review. What does it cost on the phone the user holds, including the parse and compile time minification does not remove? What does it replace, named in the product's own vocabulary, in this case date ranges the marketing site never filters by? Does any of it load before the click it serves?

With the picker, the arithmetic went this way: the range filter existed in exactly one settings pane under a route most sessions never open. The component moved behind a dynamic import, so its 214 KB travels only when the pane opens, and the budget for the route holding it stopped being anyone's problem. The next best answer, had the pane been on the landing route, would have been forty lines of two-date comparison, because date math is the kind of dependency the standard library already solved. Lazy loading is the resolution that keeps the vendor's code and your bundle apart. Rewriting is the resolution that ends the maintenance. The route decides which you can afford.

The budget is what made this a five-minute review instead of a forty-minute one. Not because the numbers are sacrosanct, but because one of them had been agreed by people who had watched it crawl.

What a green check does not mean

The honest limits, before anyone trusts the file too far. CI measures synthetic loads: your throttled 4G in CI is a simulation of a phone, not a phone, and no throttling profile captures a mid-range chipset's compile time cleanly, so a passing budget does not certify fast on the devices your users hold. Budgets gate bytes on the wire, not what the main thread does after them, and a lean bundle can still hold a long task that wrecks interaction latency. And every budget in the file expires, because routes gain features and the numbers stop defending themselves if nobody reappraises them.

The workaround that keeps the file honest is small: spot-check every budget against a real phone in real conditions when a route ships, and keep the numbers where a new engineer can read the reasoning beside them. The field data answers whether your agreements are any good. The budget answers whether anyone broke one.

That is the whole case: budgets are culture because the decision is the meeting, the file is its minutes, and CI is the only employee who never lets a 214 KB dependency through on the strength of the word "tree-shakes".

AngoraTek sets route-level performance budgets with small teams and leaves the checks running in their pipelines. If your review threads keep re-arguing bundle weight from adjectives, bring us the route where it happens and we will write the first two budgets with you.

Thanks for reading this far. If this sounds like the problem you're wrestling with, tell us about it. The team reads every message.

Start a conversation