How much JavaScript is too much?

Four tea lists, four waits

Meera has new ideas for the Leaf and Kettle tea list. Reviews under each tea. A quiz that picks a tea for you. Recipes. A chat helper. Ravi builds each one in React, like the tea list in lesson 21.2. And each one adds code to app.js, the one script the page loads.

Then Asha opens the tea list on the bus, on her phone. The shop's name appears at the top. Under it, the page stays white. She waits for the teas, and for the button that shows them all. More than five seconds pass before they come.

So Ravi and Meera ask a fair question. How much JavaScript is too much? Where is the line? This lesson finds it, one step at a time.

First, the course built the tea list four times. Each one sends more JavaScript: about 60, 150, 300 and 600 KB. Then it loaded each one on a phone like Asha's. Here is what she saw on each, 3 seconds in:

At 3 seconds, the two smaller pages showed the teas. The two bigger ones still showed only the shop's name. Same page, same phone, same network. Only the amount of JavaScript changed.

A KB here is 1,024 bytes, the way HTTP Archive counts them. Every size is compressed: it's the bytes that travel over the network. The extra code is made up for the test. It holds small made-up features. Each one has a little data, three small functions, and a React component. One feature in four belongs on the tea list. The others are for the shop's other pages. Apps that put every page's code in one file work like this.

"A phone like Asha's" means Chrome 157 set up as in lessons 21.1 and 21.2: a phone's screen, DevTools' Slow 4G network, and a CPU 4 times slower. Here is when each page could answer a tap:

1// Asha's phone: JavaScript sent (KB, compressed), and when the page could answer a tap (ms).2const pages = [3  { sent: 59, answers: 1663 },4  { sent: 150, answers: 2278 },5  { sent: 300, answers: 3320 },6  { sent: 597, answers: 5323 },7];8for (const page of pages) {9  console.log(`${page.sent} KB: answers at ${(page.answers / 1000).toFixed(1)} s`);10}

• Line 1 is a comment. A millisecond (ms) is a thousandth of a second.
• Lines 3 to 6 hold the four recorded pages. sent is the JavaScript, in KB. answers is the first moment the page could answer a tap.
• That moment is when the teas appeared, or when the last long task ended, whichever came later. The main thread runs the page's JavaScript, one task at a time. A long task keeps it busy for more than 50 ms. A tap has to wait for it.
• Lines 8 to 10 print one line per page. The first is 59 KB: answers at 1.7 s. Then come 150 KB: answers at 2.3 s, 300 KB: answers at 3.3 s and 597 KB: answers at 5.3 s.

Ten times the JavaScript, and Asha waited three times as long. Why it matters: every feature Meera adds moves the moment Asha can use the page further away.

Lesson 6.4 took a script's cost apart. This lesson turns that cost into one number Ravi can check. It goes one question at a time:

• What does the web send today? What the median page ships.
• What does each KB cost on each phone? Main-thread time per device.
• So where is the line for Leaf and Kettle? Setting a budget.
• Which bytes count? Compressed and uncompressed size.

What the median page ships

Before he picks a number, Ravi checks what other sites send. HTTP Archive is a project that loads millions of websites each month. It records every file they download, and it publishes the totals.

Its latest report gives the JavaScript on mobile home pages. Line all the pages up, from least JavaScript to most:

• The page in the middle, the median, sends 688 KB.
• The page three quarters along, the 75th percentile, sends 1,339 KB.
• The page nine tenths along sends 2,173 KB.

These are compressed bytes. The Web Almanac, HTTP Archive's yearly study, says its figures are "bytes for compressed JavaScript files." And the number keeps growing. In July 2016, the median mobile home page sent 290 KB.

How do the four tea lists compare with the median page?

1// JavaScript on HTTP Archive's median mobile home page, compressed, in KB.2const median = 688;3const pages = [59, 150, 300, 597];4for (const sent of pages) {5  console.log(`${sent} KB is ${Math.round((sent / median) * 100)}% of the median`);6}

• Line 2 is HTTP Archive's median, in KB.
• Line 3 lists the JavaScript each tea list sent.
• Lines 4 to 6 print each one as a share of the median. The first is 59 KB is 9% of the median. Then come 150 KB is 22% of the median, 300 KB is 44% of the median and 597 KB is 87% of the median.

Look at the last line. The page that kept Asha waiting 5.3 seconds sent less JavaScript than the median page. So being smaller than the median proves nothing.

The Web Almanac adds two more facts. The median mobile page asked for 22 JavaScript files. And at the median, Lighthouse, Google's test tool, found 251 KB of JavaScript unused while the page loaded. That's code downloaded, but not run, counted after unpacking.

Why it matters: the median page is a picture of the web, not a target. In lesson 1.3, the median page kept a phone's main thread blocked for nearly two seconds. A budget has to come from your own visitors.

Main-thread time on three devices

Asha's phone is only one phone. Some of Leaf and Kettle's visitors have faster ones, and some have slower ones. You can't carry every phone. So DevTools can slow your own computer's CPU down, as lesson 6.4 showed. This is called CPU throttling. The course loaded every tea list three ways:

• No slowdown, for a fast laptop. This was the recording computer, an Apple M1 Pro.
• 4 times slower, for a mid-tier phone like Asha's. DevTools has a preset for this exact setup, called "Mid-tier mobile": Slow 4G, and a CPU 4 times slower. Lighthouse slows the CPU 4 times too.
• 6 times slower, for a low-tier phone. DevTools' "Low-tier mobile" preset uses this slowdown, with a slower network as well.

The course kept Slow 4G every time, so only the CPU changed. And these are stand-ins, not real phones. Lighthouse's docs suggest 10 times slower to stand in for a low-end phone on a fast desktop. So a real cheap phone may be slower still.

Start with the 300 KB page. Its app.js arrived at almost the same moment on all three, just before 2.9 seconds. Then V8, Chrome's JavaScript engine, went to work on the main thread. It had to parse the code, which means read it. It had to compile it into steps it can follow. Then it ran it. Here is how long that took:

1// The 300 KB page: JavaScript on the main thread, in ms, on three devices.2const laptop = 71.9;3const midTier = 340.5;4const lowTier = 510.2;5console.log(`Mid-tier phone: ${(midTier / laptop).toFixed(1)} times the laptop`);6console.log(`Low-tier phone: ${(lowTier / laptop).toFixed(1)} times the laptop`);

• Lines 2 to 4 hold the recorded JavaScript time on the main thread, in ms, for each device.
• Lines 5 and 6 divide each phone's time by the laptop's. They print Mid-tier phone: 4.7 times the laptop and Low-tier phone: 7.1 times the laptop.

Same bytes, same network, very different work. Here are the three loads on one timeline:

Lesson 3.2 put a number on that wait. Total Blocking Time, or TBT, adds up the part of each long task past 50 ms, from the first contentful paint on. web.dev, Google's guide to web performance, says sites "should strive to have a Total Blocking Time of less than 200 milliseconds when tested on average mobile hardware." Here is TBT for each page on Asha's phone:

1// Asha's phone: Total Blocking Time for each page, in ms.2const tbt = { 59: 40.3, 150: 90.8, 300: 225.3, 597: 530.9 };3for (const [sent, ms] of Object.entries(tbt)) {4  console.log(`${sent} KB: ${ms} ms, ${ms < 200 ? "under" : "over"} 200`);5}

• Line 2 holds each page's recorded TBT, in ms, keyed by the KB it sent.
• Lines 3 to 5 print each one, and whether it's under 200. The first is 59 KB: 40.3 ms, under 200. Then come 150 KB: 90.8 ms, under 200, 300 KB: 225.3 ms, over 200 and 597 KB: 530.9 ms, over 200.

The two smaller pages stayed under 200 ms. The 300 KB page went over: its first long task alone ran 242 ms. And on the laptop? Even the 597 KB page had a TBT of 37.8 ms. Why it matters: a fast laptop hides the problem. Test with the phone you design for.

How much does each extra KB cost once it has arrived? Compare the smallest page with the biggest. Count from the last byte of app.js to the moment the page could answer:

1// From app.js's last byte to the first moment the page could answer, in ms: the 59 KB and the 597 KB page.2const devices = {3  "Fast laptop": [36.1, 178.6],4  "Mid-tier phone": [143.2, 759.1],5  "Low-tier phone": [216.2, 1246.4],6};7for (const [device, [small, big]] of Object.entries(devices)) {8  console.log(`${device}: ${((big - small) / (597 - 59)).toFixed(2)} ms for each extra KB`);9}

• Lines 3 to 5 hold that wait for the 59 KB and the 597 KB page on each device, in ms.
• Line 8 divides the extra wait by the extra KB: 597 minus 59.
• It prints Fast laptop: 0.26 ms for each extra KB, Mid-tier phone: 1.14 ms for each extra KB and Low-tier phone: 1.91 ms for each extra KB.

On the low-tier phone, each KB cost about seven times what it cost on the laptop. Compare all four pages on all three devices yourself:

Lighthouse used to report a similar moment, called Time to Interactive. web.dev says it "helps identify cases where a page looks interactive but actually isn't." Lighthouse 10 stopped showing it, and kept TBT.

Setting a budget for Leaf and Kettle

Now Ravi can find the line. A performance budget is a limit you set in advance. In lesson 21.2, he set one for CSS. For JavaScript, he needs three things:

1. A phone and a network to design for. Ravi picks Asha's: a mid-tier phone on Slow 4G.
2. A time goal. Ravi picks two. The tea list answers a tap within 3 seconds. And its TBT stays under 200 ms, web.dev's target.
3. What each KB costs on that phone. The recordings give him that.

Ravi does the same sum. On Asha's phone, the four recorded pages lie close to a straight line. So he draws one through the smallest and the biggest page:

1// Asha's phone: when the smallest and the biggest page could answer a tap.2const small = { sent: 59, answers: 1663 };3const big = { sent: 597, answers: 5323 };4const perKb = (big.answers - small.answers) / (big.sent - small.sent);5const start = small.answers - small.sent * perKb;6const goal = 3000;7console.log(`Each KB: ${perKb.toFixed(1)} ms. With no JavaScript: ${Math.round(start)} ms.`);8console.log(`Budget for ${goal} ms: ${Math.floor((goal - start) / perKb)} KB`);

• Lines 2 and 3 hold two recorded pages: the KB each sent, and when each could answer.
• Line 4 works out what each extra KB cost: the extra wait, divided by the extra KB.
• Line 5 follows the line back to no JavaScript at all. That's the rent: time the page needs anyway.
• Line 7 prints Each KB: 6.8 ms. With no JavaScript: 1262 ms.
• Line 8 takes the rent off the goal, divides the rest by the price of a KB, and rounds down. It prints Budget for 3000 ms: 255 KB.

Where did Asha's 6.8 ms per KB go? About 5.7 ms was the download on Slow 4G. The other 1.1 ms was the main thread. So on a slow network, most of each KB's cost is the trip. On the low-tier phone, the main thread's share grows to 1.9 ms.

Then Ravi checks the second goal, TBT under 200 ms. On Asha's phone, TBT crossed 200 ms between the 150 KB and the 300 KB page, at about 271 KB. So 255 KB passes both. Ravi rounds down, and writes down 250 KB.

Is 250 KB enough? React and the tea list alone sent 59 KB of it. React by itself, drawing an empty page, was 58 KB. That leaves about 190 KB for Meera's features.

And if many visitors have low-tier phones? The same sum there gives 225 KB. And TBT crossed 200 ms at about 146 KB. So the budget would have to shrink to about 150 KB. Your own visitors' phones decide.

Move the goal, and watch the budget change on each device:

Other people's budgets come out differently, because they start from different phones and networks:

• Alex Russell's 2026 budgets, from lesson 1.3, allow 0.3 to 0.62 MiB of JavaScript in 3 seconds. That's about 307 to 635 KB. They're bigger, because his network is faster: 9 Mbps, against Slow 4G's 1.44.
• An older web.dev guide suggests 200 KB of JavaScript for Slow 4G and a Moto G4, a mid-tier phone of its day. Its goal was a page you can use in 3 seconds.

Writing the budget down

A budget only helps if something checks it. size-limit is a tool that its docs call "a performance budget tool for JavaScript." By default, it checks a file's Brotli size. So it counts the same bytes as this lesson. Ravi adds it to package.json:

1{2  "size-limit": [3    {4      "path": "dist/app.js",5      "limit": "250 KiB"6    }7  ]8}

• Line 4 names the file to check: dist/app.js, the built script.
• Line 5 is the limit. size-limit reads kB as 1,000 bytes and KiB as 1,024. Ravi's KB are 1,024 bytes, so he writes KiB.

Lighthouse CI, which runs Lighthouse on every build, can check a page's scripts too. Its check is called resource-summary:script:size. Lesson 21.2 used the same kind of check for CSS. One warning: Lighthouse itself once had its own budget file. Lighthouse 12 removed it, so old guides that use one no longer work.

Why it matters: a budget is a sum you can redo. Pick the phone, pick the goal, measure the cost of a KB, and divide. Then let the build check it.

Compressed and uncompressed size

One question is left. Which bytes does the budget count? Every script has two sizes. The compressed size is what the server sends, after Brotli or gzip has packed it. The uncompressed size is what the phone has after unpacking it. Lesson 16.1 showed how Brotli and gzip pack text.

Here are both sizes for each tea list's app.js:

1// app.js for each page, in bytes: as built, and as sent with Brotli.2const pages = [3  { built: 241250, sent: 60828 },4  { built: 614401, sent: 153643 },5  { built: 1294767, sent: 306920 },6  { built: 2695594, sent: 611749 },7];8for (const { built, sent } of pages) {9  console.log(`${Math.round(sent / 1024)} KB sent, ${Math.round(built / 1024)} KB to read: ${(built / sent).toFixed(1)} times`);10}

• Lines 3 to 6 hold each file's recorded sizes. built is the file as the build wrote it. sent is the same file after Brotli.
• Lines 8 to 10 print both sizes in KB, and how many times bigger the unpacked file is. The first is 59 KB sent, 236 KB to read: 4.0 times. Then come 150 KB sent, 600 KB to read: 4.0 times, 300 KB sent, 1264 KB to read: 4.2 times and 597 KB sent, 2632 KB to read: 4.4 times.

Every file unpacked to about four times its size. The network carried 150 KB of the 150 KB page. V8 had to read 600 KB. As lesson 6.4 showed, compression shrinks the download, not the work.

Real sites look the same. The Web Almanac's example: amazon.co.uk "downloads 423 KB of JavaScript, but when it's uncompressed that's 1,721 KB."

A page can read both sizes of its own files. Resource Timing is the browser's list of every file a page loaded, with times and sizes:

1const app = performance2  .getEntriesByType("resource")3  .find((entry) => entry.name.endsWith("/app.js"));4console.log(`Sent: ${app.encodedBodySize} bytes`);5console.log(`Unpacked: ${app.decodedBodySize} bytes`);

• Lines 1 to 3 find the entry for app.js among the page's resources.
• Line 4 prints encodedBodySize: the body as it came over the network.
• Line 5 prints decodedBodySize: the body after unpacking.
• On the 300 KB page, they were 306,920 and 1,294,767 bytes.

The compressed size also depends on how the server packs the file. The 150 KB page's app.js was 153,643 bytes with Brotli, and 181,495 bytes with gzip. The Web Almanac 2024 looked at JavaScript requests on phones. 45% came with Brotli, and 41% with gzip. 12% came with no compression at all.

Read this table across. Each row compares the two sizes of one file:

Your browser can compress text too. Try it on the shop's real app.js, and on three other texts:

Why it matters: write the budget in compressed bytes. That's what the network pays for, and what HTTP Archive and most tools count. Then keep an eye on the unpacked size too, because that's what the phone's CPU pays for. And always say which one you mean.

Which size does it count?

Each number below comes from a tool or a report. Some count bytes sent, some count bytes unpacked, and some count time. Sort each one:

Common mix-ups

• "My page sends less than the median, so it's fine." No. The 600 KB tea list sent less than the median page, and Asha waited 5.3 seconds.
• "A 150 KB script is 150 KB of work." No. It unpacked to 600 KB, and V8 read all of it.
• "If it's fast on my laptop, it's fast." No. The 597 KB page had a TBT of 37.8 ms on the laptop, and 530.9 ms on Asha's phone.
• "6 times slower is a low-end phone." No. It's a stand-in. Lighthouse's docs suggest 10 times slower for a low-end phone, from a fast desktop.
• "kB and KB always mean the same." No. size-limit reads kB as 1,000 bytes. HTTP Archive divides by 1,024.
• "One budget fits every site." No. The same 3-second goal gave 255 KB on Asha's phone and 225 KB on a low-tier phone. A faster network gives more.

Practice exercises

Answer each one first, then open the hints if you need them.

// Asha's phone: when the smallest and the biggest page could answer a tap.
const small = { sent: 59, answers: 1663 };
const big = { sent: 597, answers: 5323 };
const perKb = (big.answers - small.answers) / (big.sent - small.sent);
const start = small.answers - small.sent * perKb;
const goal = 4000;
console.log(`Each KB: ${perKb.toFixed(1)} ms. With no JavaScript: ${Math.round(start)} ms.`);
console.log(`Budget for ${goal} ms: ${Math.floor((goal - start) / perKb)} KB`);

// app.js of the 150 KB page, in bytes, compressed two ways.
const gzip = 181495;
const brotli = 153643;
console.log(`Brotli sends ${Math.round((1 - brotli / gzip) * 100)}% fewer bytes than gzip`);

{
  "size-limit": [
    {
      "path": "dist/app.js",
      "limit": "250 KiB",
      "gzip": true
    }
  ]
}

Check your understanding

For each question, ask: which phone, which network, and which bytes?

Key takeaways

• The median mobile home page sends 688 KB of JavaScript, compressed. It's a picture of the web, not a target.
• Each KB costs time twice: the download, then parsing, compiling and running on the main thread.
• The same file costs a slower phone more: 4.7 and 7.1 times the laptop's main-thread time, on the 300 KB page.
• A budget starts from a phone, a network and a time goal. Divide the time you can spare by what each KB costs.
• Asha's phone could afford about 250 KB for a 3-second answer. A low-tier phone, about 150 KB.
• Budgets count compressed bytes. The phone reads about four times as many. Say which size you mean.

Sources

The facts on this page come from these reports, docs and source code:

• State of the Web: Page Weight, JavaScript bytes (crawl of October 1, 2026), HTTP Archive.
• Web Almanac 2025: Page Weight, HTTP Archive.
• Web Almanac 2024: JavaScript, the latest edition with a JavaScript chapter, HTTP Archive.
• Chrome DevTools: CPUThrottlingOption.ts, the CPU slowdown presets, the Chromium authors.
• Chrome DevTools: ThrottlingPresets.ts, the Mid-tier and Low-tier mobile presets, the Chromium authors.
• Lighthouse 13.6.0: Throttling, CPU throttling, Google Chrome.
• Total Blocking Time (TBT), web.dev.
• Time to Interactive (TTI), web.dev.
• The Performance Inequality Gap, 2026, Alex Russell.
• Your first performance budget, web.dev.
• Size Limit 14.3.0: README, Andrey Sitnik and contributors.
• Size Limit 14.3.0: bytes.js, how a limit is read, Andrey Sitnik and contributors.
• Lighthouse CI 0.16.0: configuration, budgets as assertions, Google Chrome.
• Lighthouse 13.6.0: resource-summary.js, sizes as transfer sizes, Google Chrome.
• Lighthouse 12.0.0 release notes: budgets removed, Google Chrome.
• PerformanceResourceTiming: encodedBodySize, MDN.
• PerformanceResourceTiming: decodedBodySize, MDN.
• CompressionStream, MDN.
• Network features reference: view the uncompressed size of a resource, Chrome for Developers.
• Performance: maxAssetSize, webpack.
• Reduce JavaScript execution time, Chrome for Developers.

Coming next: Analyzing your bundles. Ravi's app.js is over budget. Next, open it up and see which parts make it big.