Performance budgets
Set quantity, milestone, and rule budgets from your own field data and competitors, check them in the build with size-limit, and act when one breaks.
- 01Tell the three kinds of budgets apartKnow what a quantity, a milestone and a rule budget each count, and which kind notices which change.
- 02Choose budgets from dataStart from your own field and lab numbers, compare with competitors using the 20% rule, and keep a budget apart from a goal.
- 03Check budgets in the build and act on a failureMake the build fail with size-limit when a file grows too big, then optimize, remove, load later, or raise a limit on purpose.
A change nobody could see
This lesson starts Stage 13, Performance as a practice. The stages before it taught you to make a page fast. You found what was slow, and you fixed it. This stage is about the harder part: keeping a page fast. A team changes a site every week. Each change can add a few bytes or a few milliseconds. Nobody sees one of them. After a year, everyone feels all of them. This stage gives a team the habits that catch those changes early.
Leaf and Kettle isn't a one-person shop any more. Ravi runs it. Meera plans what goes on each page. Ben writes code with Ravi.
Meera wants the Mint tea reviews in a carousel: a row of cards you swipe through, one at a time. Ben picks a popular library for it, called Swiper. He follows Swiper's getting-started page and adds one small file:
import Swiper from "swiper/bundle";import "swiper/css/bundle"; export function startCarousel() { new Swiper(".reviews", { slidesPerView: "auto", spaceBetween: 12, pagination: { el: ".swiper-pagination", clickable: true }, });}- Line 1 imports Swiper with all its modules. Swiper's docs call this the bundle: one import that brings every part of the library.
- Line 2 imports Swiper's styles, again the whole set.
- Lines 4 to 10 start the carousel on the reviews, with 12 px between cards. Dots under the cards show which one you're on.
Then Ben adds two lines to app.js, the script the page loads: an import of startCarousel, and a call to it. He opens the page on his laptop. The reviews swipe. Everything else looks the same. He runs Lighthouse too, and gets 100, the same score as before.
So did the page get slower? On Ben's laptop, nobody could tell. Here is the page on Asha's phone, before and after, as Chrome drew it:
Ben's page was one step behind at each moment. At 1.24 seconds, the old page was drawing the photo, and Ben's page was still blank. At 1.30 seconds, the old page was done, and Ben's was still drawing. The gap was less than a tenth of a second. Here are the numbers behind the frames:
// Asha's phone in the lab: the middle of 5 loads, and of 3 Lighthouse runs. Bytes as sent, with Brotli.const before = { scriptBytes: 2938, photoOnScreen: 1277, score: 100 };const ben = { scriptBytes: 42836, photoOnScreen: 1341, score: 100 }; console.log(`JavaScript: ${(ben.scriptBytes / before.scriptBytes).toFixed(1)} times as many bytes`);console.log(`Photo on screen: ${ben.photoOnScreen - before.photoOnScreen} ms later`);console.log(`Lighthouse score: ${before.score}, then ${ben.score}`);- Line 1 is a comment. "Asha's phone" is the lab setup from earlier lessons: Chrome with a phone's screen, DevTools' Slow 4G network, and a CPU 4 times slower. Bytes are counted as sent: compressed with Brotli, as they travel.
- Lines 2 and 3 hold the recorded numbers. A millisecond (ms) is a thousandth of a second.
- Line 5 prints
JavaScript: 14.6 times as many bytes. Line 6 printsPhoto on screen: 64 ms later. - Line 7 prints
Lighthouse score: 100, then 100.
One number jumped. One moved a little. One didn't move at all. Why it matters: a change can cost every visitor real bytes while the page still looks right and still scores 100. Ten changes like it, and the page is slow, and nobody knows which change did it. Performance budgets and monitoring follows that story through a whole year.
So how could the team catch Ben's change before it went live? And how much is too much? The answer is a performance budget.
A busy café promises: every pot of tea on your table within five minutes. The owner picked five minutes for two reasons. Her customers stop coming back after longer waits. And the café across the road takes six. Every new dish is tried in the kitchen before it goes on the menu. A dessert that needs ten minutes in the oven doesn't go on as it is. The kitchen makes it ahead of time, or leaves it out.
- In real life: Every pot on the table within five minutes
- In web performance: A budget: a limit, like 1,300 ms until the photo shows
- In real life: What customers will wait for, and the café across the road
- In web performance: Your own field data, and your competitors' numbers
- In real life: Trying each new dish in the kitchen first
- In web performance: A check in the build, before a change goes live
- In real life: Making the slow dessert ahead, or leaving it out
- In web performance: Loading a feature later, or not adding it
A performance budget is a limit on a number that affects speed, which the team agrees not to cross. You choose it from data. A check fails the build when a change crosses it. Then the team decides: make the change lighter, load it later, leave it out, or raise the limit on purpose.
web.dev defines a budget as "a set of limits imposed on metrics that affect site performance." Tim Kadlec adds the team: a limit "that the team agrees not to exceed". If it isn't clearly defined, agreed and used, he says, "then it's a number or goal, but not a budget."
You've set budgets before: for CSS in lesson 21.2, for JavaScript in lesson 22.1, and for each third-party tag in lesson 24.3. This lesson sets them for a whole page, and keeps them. It goes one question at a time:
- What kinds of budgets are there?
- Where do the numbers come from?
- How does the build check them?
- What happens when one breaks?
How the course recorded it
- The pages: the Mint tea page built three ways with esbuild 0.28.2: before Ben's change, with his carousel (Swiper 14.4.0), and with the fix you'll meet at the end.
- The lab: Chrome 157 as Asha's phone. Each version loaded 5 times, taking turns. The lesson quotes the middle load.
- Lighthouse: version 13.6.0, with its usual phone settings, 3 runs of each version.
- The field: 40 phone visits to the page before Ben's change. Each phone had its own speed and network, drawn the way lesson 13.1 drew them. The page sent its own numbers home with web-vitals, as in lesson 12.4.
- The competitors: HTTP Archive's Technology Report, from lesson 36.6.
- The build check: size-limit 14.3.0, run on each build.
Quantity, milestone, and rule budgets
web.dev sorts the numbers a budget can limit into three kinds. Each kind counts something different. So each kind notices different changes.
- Quantity: sizes and counts. How many bytes of JavaScript, CSS and images? How many fonts, how many requests? web.dev says these are easy to explain to designers and developers alike.
- Milestone: moments in a visit that a person sees or feels. When did the photo show? That's LCP, Largest Contentful Paint. How fast did a tap answer? That's INP. Did anything jump? That's CLS.
- Rule: a score a tool works out from its own rules. Lighthouse's Performance score, from 0 to 100, is the best known.
In the lab there's no real tap, so Total Blocking Time, or TBT, stands in for INP. A long task keeps the main thread busy for more than 50 ms. TBT adds up the part of each long task past those 50 ms.
A school report holds three kinds of numbers. Days missed is a count. Each test has its own mark. At the bottom sits one overall grade. A pupil can keep the same grade while one subject slips, because the others hold it up. Each number tells the parents something the others can't.
- In real life: Days missed
- In web performance: A quantity: bytes or requests
- In real life: The mark in each test
- In web performance: A milestone: LCP, INP, CLS
- In real life: The overall grade at the bottom
- In web performance: A rule: Lighthouse's score
- In real life: The same grade while one subject slipped
- In web performance: A score of 100 while the photo came later
Here are five of the page's numbers, before and after Ben's change:
// The same five numbers, before and after Ben's change, on Asha's phone.const before = { scriptBytes: 2938, requests: 4, lcp: 1277, tbt: 0, score: 100 };const ben = { scriptBytes: 42836, requests: 4, lcp: 1341, tbt: 0, score: 100 }; for (const name of Object.keys(before)) { const seen = ben[name] === before[name] ? "no change" : `${before[name]} to ${ben[name]}`; console.log(`${name}: ${seen}`);}- Lines 2 and 3 hold the recorded numbers.
scriptBytesandrequestsare quantities.lcpandtbtare milestones.scoreis a rule. - Lines 5 to 8 compare each pair. Line 6 says "no change" when the two numbers are equal.
- It prints
scriptBytes: 2938 to 42836,requests: no changeandlcp: 1277 to 1341. Thentbt: no changeandscore: no change.
Each kind saw a different part of the change:
- The request count didn't move. esbuild, the tool that builds Ravi's code, put Swiper inside
app.js. The page still loaded 4 files. One of them was just 14.6 times bigger. Why it matters: a count of files misses a file that grows. - TBT stayed at 0. Ben's
app.jsran for about 31 ms on Asha's phone, against 6 ms for the old one. That's still under 50 ms, and no other task was long either. Why it matters: TBT only counts work in long tasks. - The score stayed at 100. Lighthouse's own LCP went from 901 ms to 1,051 ms, and it still gave full marks. Near the top, the score has room. Why it matters: a score is a summary, so a rule budget can't stand alone.
- The photo came 64 ms later. Swiper's styles made
app.cssbigger, and the page can't paint before its CSS arrives. It arrived at 1,202 ms instead of 1,169 ms. And the photo shared Asha's slow network with 42.84 kB of JavaScript: it finished at 1,335 ms instead of 1,260 ms.
So which kind should a team use? Tim Kadlec recommends a timing as the main budget, because it's what visitors feel. Bytes and scores make good supporting budgets. He also suggests turning the timing into quantities, which designers and developers can check every day while they work. web.dev agrees: track a mix of quantities and timings.
Setting budgets from field data and competitors
Now Ravi needs numbers. web.dev's guide to a first budget starts with your most important pages. For Leaf and Kettle, that's the Mint tea page: most people buy from it. Then the guide compares them with competitors. SpeedCurve's guide adds a rule for where to draw the line. Ravi uses all three.
Start from your own field data
Field data comes from real visits. Ravi's page sends its own numbers home, so he can read them. Here are the p75s of 40 phone visits before Ben's change. The p75, or 75th percentile, is the value that three visits in four matched or beat.
// Ravi's field data: the p75 of 40 phone visits before Ben's change. LCP and INP in ms.const p75 = { LCP: 580, INP: 48, CLS: 0 };const good = { LCP: 2500, INP: 200, CLS: 0.1 }; for (const name of Object.keys(p75)) { console.log(`${name}: ${p75[name]}, good up to ${good[name]}`);}- Line 2 holds Ravi's recorded p75s. CLS has no unit: it's a score for how far things moved.
- Line 3 holds web.dev's good lines for the three Core Web Vitals. web.dev says to check them at the 75th percentile of page loads, "segmented across mobile and desktop devices."
- Lines 5 to 7 print
LCP: 580, good up to 2500,INP: 48, good up to 200andCLS: 0, good up to 0.1.
Ravi passes all three, easily. So should his LCP budget be 2,500 ms? No. That's more than four times his p75. The page could get four times slower, and that budget would still pass. Why it matters: a good line is a ceiling. A budget must sit close to where you are, or it never fails.
Look at your competitors
Next, web.dev's guide says to compare with sites like yours, about ten of them. It also says how much faster is worth being. The research it cites found that people notice a difference in response times when it's more than 20%. So, in the guide's words, "if you want to be noticeably better than the best comparable site, you have to be at least 20% faster."
A runner wants to know how fast she is. Her own runs this month tell her where she is today. The club's results board tells her where everyone else is. She writes down two numbers. Her goal: a fifth faster than the club's middle runner, enough for people to notice. Her limit: never slower than her worst run this month.
- In real life: Her own runs this month
- In web performance: Your field data and lab runs
- In real life: The club's results board
- In web performance: Competitors' field data, from CrUX
- In real life: A fifth faster than the club's middle runner
- In web performance: web.dev's 20% rule: a goal people would notice
- In real life: Never slower than her worst run this month
- In web performance: A budget: today's worst number
Ravi can't test ten tea shops by hand. But many online shops are built on Shopify, as lesson 36.6 showed. HTTP Archive's Technology Report finds which platform each site runs on, and joins that with CrUX, Chrome's field data from lesson 10.1. For 451,213 Shopify stores, it counts how many had each p75 LCP on phones. It counts them in buckets: 100 ms wide for LCP, and 25 ms for INP. Those are the steps CrUX's summary uses for each store's p75.
// Phones. Ravi: the p75 of 40 visits. The middle Shopify store: the start of its CrUX p75's bucket.const ravi = { LCP: 580, INP: 48 };const middleStore = { LCP: 1500, INP: 100 }; for (const name of Object.keys(ravi)) { const line = Math.round(middleStore[name] * 0.8); console.log(`${name}: 20% faster than the middle store is ${line} ms. Ravi: ${ravi[name]} ms.`);}- Line 1 is a comment. The middle store is the one in the middle of the line: half the stores were faster, half slower. Its p75 LCP was between 1,500 and 1,599 ms. The code uses the start, 1,500 ms.
- Line 2 holds Ravi's p75s. Line 3 holds the middle store's, for LCP and INP.
- Line 6 takes 20% off: it multiplies by 0.8.
- It prints
LCP: 20% faster than the middle store is 1200 ms. Ravi: 580 ms.andINP: 20% faster than the middle store is 80 ms. Ravi: 48 ms.
Ravi's page is small, so it's fast. Fewer than 1 store in 100 had a p75 LCP under 600 ms: 0.3%. Why it matters: for Ravi, the competitors' line isn't a goal to reach. It's a lead to keep. Try the stores a quarter and three quarters of the way along the line:
- That store's p75 LCP1,500 to 1,599 ms
- 20% faster than that LCP bucket's start1,200 ms
- Ravi's p75 LCP580 ms
- That store's p75 INP100 to 124 ms
- 20% faster than that INP bucket's start80 ms
- Ravi's p75 INP48 ms
web.dev's 20% rule says people notice a difference of more than 20%. Staying under this line keeps Ravi noticeably faster than this store.
A budget is not a goal
SpeedCurve's guide draws a clear line between the two. A goal answers "How fast do I want to be eventually?" A budget answers "How can I keep my site from getting slower while I work toward my performance goals?" For the budget, it says: look at the last 2 to 4 weeks of a metric, find the worst number, and set the budget there. A budget you already break can't warn you when things get worse.
Ravi takes that rule to his lab: Asha's phone, 5 loads before Ben's change. Bytes are simpler. The same build always sends the same bytes, so there's nothing to wait out. He only leaves room for small fixes: a tenth more than today, rounded up.
// The 5 lab loads before Ben's change: LCP in ms. The bytes app.js and app.css sent, with Brotli.const lcps = [1290.1, 1277.1, 1285.3, 1268.5, 1276.6];const sent = { "app.js": 2938, "app.css": 392 }; const lcpBudget = Math.ceil(Math.max(...lcps) / 100) * 100;console.log(`LCP budget: ${lcpBudget} ms`);for (const [file, bytes] of Object.entries(sent)) { console.log(`${file} budget: ${Math.ceil((bytes * 1.1) / 1000)} kB`);}- Line 2 holds the 5 recorded LCPs. Line 3 holds the bytes
app.jsandapp.csssent. - Line 5 takes the slowest load, 1290.1 ms, and rounds it up to the next 100 ms. Line 6 prints
LCP budget: 1300 ms. - Lines 7 to 9 add a tenth to each file and round up to a whole kB. A kB here is 1,000 bytes. They print
app.js budget: 4 kBandapp.css budget: 1 kB.
Three more lines come from outside, where today's number is 0 and a budget of 0 would fail on the smallest change:
- TBT under 200 ms, web.dev's target "when tested on average mobile hardware."
- CLS at most 0.1, the good line.
- A Lighthouse score of at least 90, where Lighthouse's green band starts. web.dev's guide suggests at least 85.
And for the field, Ravi writes down a p75 LCP of at most 600 ms: his 580 ms, rounded up. Why two LCP budgets? They measure different visits. The lab is one slow phone on Slow 4G. The field is many phones on many networks, most of them faster. SpeedCurve's guide says the two "most likely will not match", and that's fine. Compare each one only with itself.
Here are all of Ravi's lab and build budgets. Check Ben's page against them:
- JavaScript at load (quantity, build)2.94 kB of 4 kB: 1,062 B left
- CSS at load (quantity, build)392 B of 1 kB: 608 B left
- Requests at load (quantity, lab)4 of 4: 0 left
- LCP on Asha's phone (milestone, lab)1,277 ms of 1,300 ms: 23 ms left
- Total Blocking Time (milestone, lab)0 ms of 200 ms: 200 ms left
- Cumulative Layout Shift (milestone, lab)0 of 0.1: 0.1 left
- Lighthouse Performance (rule, lab)100 of 90: 10 above the line
Each number is on the right side of its line, so the build and the lab checks would both pass.
A budget check in the build
A budget only helps if something checks it, every time, without anyone having to remember. The build is the place: the step that turns Ravi's source files into the files the site serves. Every change goes through it before it goes live.
A car park has a bar across its entrance, at the height of its lowest ceiling. Nobody stands there measuring vans. A van that's too tall hits the bar at the entrance, before it can get stuck inside. A sign next to the bar gives the height, and says where tall vans can go instead.
- In real life: The bar's height
- In web performance: The limit: 4 kB of JavaScript at load
- In real life: Every vehicle passes under it
- In web performance: Every build runs the check
- In real life: Stopped at the entrance
- In web performance: The build fails, before the change goes live
- In real life: The sign next to the bar
- In web performance: The message in the budget's settings
Ravi's check is size-limit, from lesson 22.1. Its docs call it "a performance budget tool for JavaScript." Its file plugin measures each file with Brotli, the way a server sends it. Ravi gives it two checks, in package.json:
{ "size-limit": [ { "name": "JavaScript at load", "path": "dist/app.js", "limit": "4 kB", "message": "Load big libraries with import() when they're needed. Ask Ravi before raising a limit." }, { "name": "CSS at load", "path": "dist/app.css", "limit": "1 kB", "message": "Load big libraries with import() when they're needed. Ask Ravi before raising a limit." } ]}- Line 2 starts the list of checks. Each item in it is one check.
- Lines 4 and 10 give each check a
name, which the output prints. - Lines 5 and 11 give the
pathof the file to measure:dist/app.jsanddist/app.css, the built files the page loads at the start. - Lines 6 and 12 are the limits: 4 kB and 1 kB. size-limit reads kB as 1,000 bytes.
- Lines 7 and 13 hold a
message, which size-limit prints when a check fails. Ravi's says what to do, and who to ask.
The same file has a script, npm run check. It builds the page, then runs size-limit. When a check fails, size-limit ends with an error code, so the whole command fails too. Ben's pull request, his change waiting for the team to review it, ran the check. Here is what size-limit printed:
$ npx size-limitJavaScript at loadPackage size limit has exceeded by 38.84 kBLoad big libraries with import() when they're needed. Ask Ravi before raising a limit.Size limit: 4 kBSize: 42.84 kB brotlied CSS at loadPackage size limit has exceeded by 1.78 kBLoad big libraries with import() when they're needed. Ask Ravi before raising a limit.Size limit: 1 kBSize: 2.78 kB brotlied Try to reduce size or increase limit in "size-limit" section of package.json- Lines 2 to 6 are the JavaScript check. Line 3 says how far over it went. Line 4 is Ravi's message. Lines 5 and 6 give the limit and the size: 42.84 kB, against 4 kB.
- Lines 8 to 12 are the CSS check: 2.78 kB against 1 kB. Swiper's styles went into
app.css. - Line 14 points at where the limits live.
size-limit ended with exit code 1, and the build failed. On the build before Ben's change, the same command ended with exit code 0. Here is Ben's app.js against the bar:
Why it matters: the bytes check failed in seconds, before anyone loaded the page. Seeing the photo's 64 ms takes a browser, several loads and careful numbers.
Other ways to check
- webpack, a popular bundler, checks its own output.
performance.maxAssetSizeandperformance.maxEntrypointSizeare 250,000 bytes each unless you change them. They count the bytes of each file webpack writes. In production mode, webpack only warns by default. - Lighthouse once read a budget file of its own. Its changelog for version 12.0.0 lists "remove budgets", as lesson 8.5 showed. Today a custom audit does that job.
- Milestone budgets need a browser. Running Lighthouse CI and lab loads on every pull request, without letting noise fail good changes, is the next lesson.
What to do when a budget is broken
The check failed. Now what? web.dev lists three ways out:
- Optimize an existing feature or file.
- Remove an existing feature or file.
- Don't add the new feature or file.
A fourth way is always there: raise the limit. Kadlec's definition says the team agrees on the limit, so only the team can move it. Ravi's message says it plainly: ask Ravi first.
A lift beeps when too many people step in. The doors stay open. Someone steps out and takes the next trip. Or someone leaves a heavy box for later. Or the group takes the stairs. Nobody cuts the alarm's wire. If the lift is always too small, the owner fits a bigger one, and everyone knows why.
- In real life: The beep
- In web performance: The failed check
- In real life: Stepping out for the next trip
- In web performance: Loading the carousel later
- In real life: Leaving the heavy box behind
- In web performance: Importing less of the library
- In real life: Taking the stairs
- In web performance: Not adding the feature
- In real life: The owner fits a bigger lift
- In web performance: The team raises the limit, on purpose
The team looks at each way out for the carousel:
- Optimize: import less. Swiper's docs say its default import brings only the core, and you add the modules you use, such as the dots.
- Optimize: load it later. The reviews start 1,152 px down the page, below the 823 px screen. Asha only needs the carousel if she scrolls there.
- Remove, or don't add. Keep the plain list of reviews.
- Raise the limit to 43 kB. Then every visitor pays for the carousel, even those who never scroll to the reviews.
Ravi and Ben choose to load it later. The carousel's code stays the same. Ben moves Swiper's styles out of carousel.js into a file of their own, carousel.css. That's needed because esbuild gathers every CSS file app.js reaches into app.css. Then he changes app.js:
import "./app.css";import { addToCart } from "./cart.js";import { startRum } from "./rum.js"; document.querySelector("#add").addEventListener("click", addToCart);startRum(); const reviews = document.querySelector(".reviews");const observer = new IntersectionObserver(async ([entry]) => { if (!entry.isIntersecting) return; observer.disconnect(); const styles = Object.assign(document.createElement("link"), { rel: "stylesheet", href: "carousel.css" }); document.head.append(styles); const { startCarousel } = await import("./carousel.js"); startCarousel();});observer.observe(reviews);- Lines 1 to 6 are
app.jsas it was before Ben's change: the styles, the cart and the field data. - Line 8 finds the reviews.
- Line 9 makes an IntersectionObserver: the browser calls the function inside when an element comes on screen or leaves it.
- Line 10 does nothing until the reviews are on screen. Line 11 stops watching, so the carousel starts only once.
- Lines 12 and 13 add a link to
carousel.css, so the browser fetches Swiper's styles now. - Line 14 fetches
carousel.jswithimport(), and waits for it. As in lesson 22.4, the build gives that code a file of its own. - Line 15 starts the carousel. Line 17 starts watching the reviews.
The course loaded the fix on Asha's phone. On one more load, it scrolled down to the reviews:
// The fix on Asha's phone. Bytes as sent: at the start, and after a scroll to the reviews.const atStart = { scripts: 3084, styles: 436 };const afterScroll = { carouselCode: 40146, carouselStyles: 2424 }; const total = (files) => Object.values(files).reduce((sum, bytes) => sum + bytes, 0);console.log(`At the start: ${total(atStart)} bytes`);console.log(`After the scroll: ${total(afterScroll)} bytes`);- Line 2 holds the JavaScript and CSS the page sent at the start. Line 3 holds what came after the scroll.
- Line 5 adds up each group.
- It prints
At the start: 3520 bytesandAfter the scroll: 42570 bytes.
The check passes again: app.js is 3.08 kB, under 4 kB. On Asha's phone, the photo showed at 1,289 ms, back under the 1,300 ms budget. The carousel's files came only after the scroll, and had all arrived 0.8 seconds later. Nothing on the page moved when the carousel started. Why it matters: every visitor gets the page as fast as before. Only people who reach the reviews pay for the carousel, and they pay when they need it.
Compare all three versions against every budget:
- JavaScript at load (quantity, build)2.94 kB of 4 kB: 1,062 B left
- CSS at load (quantity, build)392 B of 1 kB: 608 B left
- Requests at load (quantity, lab)4 of 4: 0 left
- LCP on Asha's phone (milestone, lab)1,277 ms of 1,300 ms: 23 ms left
- Total Blocking Time (milestone, lab)0 ms of 200 ms: 200 ms left
- Cumulative Layout Shift (milestone, lab)0 of 0.1: 0.1 left
- Lighthouse Performance (rule, lab)100 of 90: 10 above the line
Each number is on the right side of its line, so the build and the lab checks would both pass.
One more habit. SpeedCurve's guide says to look at your budgets again every 2 to 4 weeks, and adjust them, hopefully downward, as the page improves. Set them from good weeks, not from the week something went wrong.
Which kind of budget?
Here are the three kinds side by side. Read each row across: what the kind counts, one of Ravi's budgets, and what Ben's change did to it.
| Kind | What it counts | One of Ravi's budgets | What Ben's change did |
|---|---|---|---|
| Quantity | Sizes and counts: bytes of JavaScript, CSS and images, and requests. | app.js may send 4 kB. The page may make 4 requests. | The JavaScript budget failed. The request count stayed at 4. |
| Milestone | Moments a visitor sees or feels: LCP, INP, CLS, and TBT in the lab. | The photo must be on screen by 1,300 ms on Asha's phone. | The photo came 64 ms later, past the budget. |
| Rule | A score from a tool's rules, such as Lighthouse's Performance score. | Lighthouse must score at least 90. | It scored 100 before and after. |
Now sort these budgets by their kind:
- app.js sends at most 4 kB with Brotli
- At most 4 requests when the page loads
- No more than 2 web fonts on a page
- The photo is on screen by 1,300 ms on Asha's phone
- The p75 LCP of phone visitors stays at or under 600 ms
- Cumulative Layout Shift stays at 0.1 or less
- Lighthouse's Performance score is at least 90
- A passing grade from WebPageTest's checks
Sort each budget by what it limits: a size or count, a moment, or a tool's score.
Common mix-ups
- "A budget is a goal to work toward." No. A goal is how fast you want to be one day. A budget is the line you won't cross while you get there.
- "A Lighthouse score of 100 means nothing got worse." No. Ben's page scored 100 with 14.6 times the JavaScript, and the photo 64 ms later.
- "Set the budget at the Core Web Vitals line." No. Ravi's p75 LCP was 580 ms. A 2,500 ms budget would let it grow four times before any check failed.
- "A lab budget and a field budget for LCP should be the same number." No. They measure different visits: 1,300 ms on Asha's Slow 4G phone, 600 ms at the p75 of real phones.
- "A request budget catches a big new library." No. The bundler put Swiper inside
app.js. The page still made 4 requests. - "A failed budget means the feature can't ship." No. The carousel shipped, loaded later. Optimize, remove, don't add, or raise the limit on purpose.
Practice exercises
Answer first, then use the hints.
Ravi checks himself against a faster store. What does this print?
// The Shopify store a quarter of the way from the fastest: the start of its p75 LCP's bucket, in ms.
const fastQuarterStore = { LCP: 1100 };
console.log(`Budget: ${Math.round(fastQuarterStore.LCP * 0.8)} ms`);Budget: 880 ms. To be noticeably faster than the store a quarter of the way from the fastest, Ravi would need a p75 LCP of 880 ms or less. He's at 580 ms.
Suppose Ravi had set his LCP budget from Ben's loads instead. What does this print?
// Ben's 5 lab loads: LCP in ms.
const lcps = [1340.7, 1342.8, 1345.4, 1340, 1335.8];
console.log(`Budget: ${Math.ceil(Math.max(...lcps) / 100) * 100} ms`);Budget: 1400 ms. A budget set from the week of a regression locks the regression in: Ben's slower page would pass it. Set budgets from good weeks.
With the fix, how many bytes are left under the JavaScript budget?
916 bytes. The fix's app.js sends 3,084 bytes against a limit of 4,000: the carousel's code no longer counts.
What INP line does the 20% rule give for the store three quarters of the way from the fastest, in ms?
120 ms. That store's p75 INP was in the bucket from 150 ms, and 20% off 150 is 120. Ravi's p75 INP is 48 ms.
Open the fixed Mint tea page in Chrome, with DevTools' Network panel open. Scroll down to the reviews. Which JavaScript file arrives?
carousel-CVTXP5GF.js: Swiper and Ben's carousel code. esbuild gave it a file of its own, named after carousel.js with a hash, because app.js loads it with import().
In production, webpack only warns about big files. Which value of performance.hints makes the build fail instead?
"error". webpack then reports a file over maxAssetSize as an error, not a warning. Its docs recommend it for production builds, to help stop a bundle that's too big from being deployed.
Check your understanding
For each question, ask: what does this budget count, and where does its number come from?
Question 1 of 7Which kind of budget is "Lighthouse's Performance score is at least 90"?
Choose an answer to see the explanation.
Question 2 of 7Which of Ravi's budgets did NOT notice Ben's carousel?
Choose an answer to see the explanation.
Question 3 of 7Ravi's p75 LCP is far under the good line of 2.5 seconds. Why not make 2.5 seconds his LCP budget?
Choose an answer to see the explanation.
Question 4 of 7What does web.dev's 20% rule say?
Choose an answer to see the explanation.
Question 5 of 7What does this budget check print?
Read the code, then predictconst limit = 4000; const sizes = [2938, 42836, 3084]; console.log(sizes.filter((size) => size > limit).length);Choose an answer to see the explanation.
Question 6 of 7The JavaScript budget fails on a pull request. Which of these is NOT one of the ways to deal with it?
Choose an answer to see the explanation.
Question 7 of 7Why did the request budget not notice Ben's change?
Choose an answer to see the explanation.
Key takeaways
- A performance budget is a limit the team agrees not to cross, checked on every change.
- Quantity budgets count bytes and files. Milestone budgets time what visitors feel. Rule budgets use a tool's score.
- Each kind notices different changes. Ben's carousel failed the bytes budget, moved the photo a little, and left the score at 100.
- Start from your own data: today's worst number for timings, a little room for bytes. Good lines are ceilings, not budgets.
- Compare with competitors. web.dev's 20% rule: to be noticeably faster, be at least 20% faster.
- When a budget breaks: optimize, load later, remove, don't add, or raise the limit on purpose, as a team.
Remember the one-liner.
A budget is a line you choose from data and check on every change, so small slips are caught while they're small.
Sources
The facts on this page come from these docs and data:
- Getting started with Swiper, Swiper.
- Performance budgets 101, web.dev.
- Performance budgets that stick, Tim Kadlec.
- Total Blocking Time (TBT), web.dev.
- Lighthouse performance scoring, Chrome for Developers.
- Your first performance budget, web.dev.
- Web Vitals, web.dev.
- Technology Report API, HTTP Archive.
- reportService.js: how the CWV distribution counts stores, HTTP Archive.
- A complete guide to web performance budgets, SpeedCurve.
- Size Limit, Andrey Sitnik and contributors.
- Performance (configuration), webpack.
- Lighthouse changelog: 12.0.0, Google Chrome.
- Content types: CSS, Import from JavaScript, esbuild.
Coming next: Performance in continuous integration. Lab checks and Lighthouse CI on every pull request, with limits that noise can't trip.