By Mehdi HassanWhat is a performance budget?
A performance budget is a set of agreed limits on how heavy and slow a website's pages may get, checked on every release. It turns a vague goal, "keep the site fast", into numbers a build can pass or fail.
Without a budget, speed decays one reasonable decision at a time: a new animation library, a bigger hero video, another tracking pixel. Each looks harmless alone. A budget makes the cost visible at the moment someone adds it, when it's cheap to change, rather than months later when the site fails Core Web Vitals and nobody remembers why. It also gives designers, marketers and developers a shared language for trade-offs: if a new feature needs room, something else has to give.
What should a web performance budget measure?
A web performance budget should measure three layers: the metrics visitors feel, the resources that cause them, and the third-party scripts you don't control. Each catches problems the others miss.
Layer | What to budget | Why it matters |
|---|---|---|
User-facing metrics | LCP, INP and CLS on key templates | What Google measures and visitors feel |
JavaScript | Total JS per page, largest bundle | The main cause of slow responsiveness |
Page weight | Total transfer size, hero image size | Matters most on mobile data |
Fonts | Number of font files, preloaded files | Affects text rendering and layout shift |
Third-party scripts | Count and main-thread time | The part of the budget most likely to grow |
Requests | Total requests on first load | A simple early warning for bloat |
Metrics are the goal; resource limits are how you protect it. A page can pass LCP today and fail next month because someone doubled the JavaScript. Resource budgets catch that in review, before visitors feel it.
What is a good starter performance budget for a marketing site?
A good starter budget for a marketing site uses Google's Core Web Vitals thresholds for the metrics and your own current measurements for everything else. Generic kilobyte limits copied from a blog post rarely fit your stack, design or audience.
Google defines a good experience as LCP within 2.5 seconds, INP within 200 milliseconds and CLS under 0.1, measured at the 75th percentile of real visits. Google's Web Vitals documentation explains the thresholds. Those are your metric budget. For resources, start from what you have:
- Measure key templates. Homepage, pricing, a landing page, a blog post and the signup or demo page.
- Record the current values for JavaScript, page weight, font files, requests and third-party scripts on each.
- Set the budget at today's value where the template already passes Core Web Vitals, so it can't get worse.
- Set a lower target where it fails, and plan the work to get there.
- Review and tighten the limits each quarter as you remove waste.
Hypothetical example: a starter budget sheet
For example, suppose a startup measures its homepage and finds it passes LCP and CLS but fails INP on mobile, with one large animation library and several third-party scripts. Its starter budget sheet says: Core Web Vitals at Google's good thresholds; homepage JavaScript capped at today's measured total; no new third-party scripts without removing one; hero image no larger than today's file; two font files preloaded at most.
The INP failure gets its own target and a fix plan: load the chat widget on click and replace the animation library on this page with CSS. Once INP passes, the team lowers the JavaScript limit to the new, smaller total.
How do you enforce a performance budget in CI?
You enforce a performance budget in CI by running automated checks on every pull request and failing the build when a page or bundle goes over its limit. That way the budget is checked by a machine on every change, not remembered by a person once a quarter.
Check bundle sizes on build
Add a size check to the build that compares JavaScript output against the budget. A bundle analyzer shows what each route ships, and size-checking tools can fail the job when a bundle grows past its limit.
Run Lighthouse CI on preview deployments
Point Lighthouse CI at the preview URL for each pull request, for your key templates, and set assertions for resource sizes, request counts and lab metrics.
Run several times and use the median
Lab results vary between runs. Running a few times and asserting on the median avoids failing builds because of noise.
Fail loudly, with a reason
Make the failure message say which page, which limit and by how much. A vague red cross gets overridden; a specific one gets fixed.
Watch the field separately
CI can't measure real visitors. Review Search Console's Core Web Vitals report or your real-user monitoring each month to confirm the lab budget is protecting the field result.
Lab checks can disagree with real-user data, which is why both layers matter. Our explainer on PageSpeed Insights scores versus real-user data covers why.
What happens when a change goes over the budget?
When a change goes over budget, the team either makes room by removing something, optimizes the change until it fits, or agrees explicitly to raise the limit. The worst option is the silent one: overriding the check and moving on.
Give each budget an owner, usually the lead developer on the site, who decides between those three options with whoever requested the feature. Raising a limit is allowed, but it should be written down with a reason. Over time that record shows where the weight went and what it bought. Third-party scripts deserve the strictest rule, because they're added outside code review. Our third-party script audit method pairs well with a budget: no new script without an inventory row, an owner and room in the allowance.
How do design decisions fit into a performance budget?
Design decisions fit into a performance budget because most page weight is decided before code is written: the hero media, the animation style, the number of fonts and the components on each page. A budget works best when designers know it exists.
- Hero media. A still product shot and a looping video have very different costs. See image and video optimization for fast marketing sites.
- Motion. CSS transitions are nearly free; scroll-driven animation libraries are not. Our guide to scroll animations without killing performance covers the trade-offs.
- Components. A page builder with a fixed set of well-built blocks keeps weight predictable. See page builder blocks marketers can use.
- Landing pages. Campaign pages get built fast and often skip review, so budget them explicitly. Our guide to fast landing pages shows how to keep the design intact.
When one team owns words, design and code, as ours does, the budget becomes a design brief constraint rather than a developer's complaint after the fact.
What are the common mistakes with performance budgets?
The common mistakes are budgets nobody enforces, budgets copied from someone else's site, and budgets that only cover lab scores. Each leaves the site slowly getting heavier while the dashboard looks fine.
- Only budgeting the PageSpeed score. A single score hides which resource grew. Budget the resources too.
- One number for every page. Template-level budgets are fairer and more useful.
- No owner. A budget without someone accountable gets overridden the first time a deadline is close.
- Ignoring third parties. Tag managers let scripts in without code review, so the CI check never sees them unless you test the live configuration.
- Never tightening. After a clean-up, lower the limit to lock in the gain.
