---
title: "Fail the build when pages get heavier · Agent Wranglers"
url: https://agentwranglers.se/playbook/website/performance/performance-budget
updated: 2026-10-20
licence: "All rights reserved"
---

# Fail the build when pages get heavier

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Required
- Chapter: [Performance](https://agentwranglers.se/playbook/website/performance)
- Rule: Set a budget for page weight, request count and lab metrics, and make the build fail when a change goes over it.
- How: Pick limits from your measured pages, with a little headroom. Run a lab tool on key pages in the build, such as Lighthouse CI with assertions. Check the size of every script and stylesheet the build writes. Raise a limit only on purpose, in its own reviewed change. See also [give each route a size budget](https://agentwranglers.se/playbook/app-ui/tests-and-budgets/route-bundle-budget).
- Check: Add a large image or script on a branch. The build fails and names the budget that was passed.

Example:

```json
{
  "ci": {
    "assert": {
      "assertions": {
        "resource-summary:total:size": ["error", { "maxNumericValue": 300000 }],
        "resource-summary:script:count": ["error", { "maxNumericValue": 3 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }]
      }
    }
  }
}
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers website playbook: https://agentwranglers.se/playbook/website/performance/performance-budget`.

- Previous: [Report how long the server took](https://agentwranglers.se/playbook/website/performance/server-timing)
- [Performance](https://agentwranglers.se/playbook/website/performance)