Loading performance

Send less, start sooner

When you open a web page, the browser must download files and run code before you can use the page. Loading performance is about making that wait short. The main way to do it is simple: make the browser do less work before the page is useful.

Here are three ways to save time, best first:

1. Don't send code the page doesn't need.
2. Send code later, at the moment the user needs it.
3. Let the browser keep code and reuse it on the next visit.

This lesson builds on bundlers, dynamic import, page lifecycle, Cache API and file storage, service workers, and engines and runtimes. Two later lessons go further: measuring performance and keeping the main thread responsive.

A JavaScript file costs more than its download. The server usually sends it compressed: squeezed smaller, like a zip file. Then the JavaScript engine, the part of the browser that runs JavaScript, has more work to do. In order, the browser must:

1. Download the compressed file.
2. Decompress it back into the full source text.
3. Parse it: read the text and work out how the code is built.
4. Compile it: turn it into instructions the computer can run.
5. Execute it: run the code.

An image can be bigger than a script. But byte for byte, a script usually makes the phone's processor (the CPU) work much harder before the page responds.

The table below shows the five jobs. Read each row as: "at this job, the browser pays this."

How much JavaScript do real pages send? The 2024 Web Almanac JavaScript chapter answers that. It was published on March 3, 2025, from pages measured in June 2024. It found:

• The middle page (the median) sends 558 KB of JavaScript on mobile and 613 KB on desktop.
• JavaScript on mobile pages grew by 14% in one year.

web.dev's guide to JavaScript start-up adds a warning. An average phone can have a slow CPU, a small cache, and little free memory. So a fast office laptop doesn't show what most users see.

Chrome's Network panel shows two sizes for each file:

• The transferred size is the compressed file that came over the network.
• The resource size is the file after decompression. It is close to the text the engine parses.

The numbers below come from one measured script. Other scripts shrink by different amounts.

const script = { transferredKb: 82, resourceKb: 250 };
console.log("Transferred: " + script.transferredKb + " KB");
console.log("Resource: " + script.resourceKb + " KB");

Line 1 stores the two measured sizes. Line 2 prints Transferred: 82 KB. Line 3 prints Resource: 250 KB. The browser downloads 82 KB but parses 250 KB. So a small download doesn't mean cheap parsing.

How do the browser and the server agree on compression? With HTTP headers: short notes sent along with a request and with a response.

GET /assets/app.js
Accept-Encoding: br, gzip

HTTP/2 200
Content-Encoding: br
Vary: Accept-Encoding

Line by line:

• Line 1: the browser asks for app.js.
• Line 2: Accept-Encoding lists the formats the browser can decompress: Brotli (br) or gzip.
• Line 4: the server answers. 200 means "OK, here is the file".
• Line 5: Content-Encoding: br says the server picked Brotli.
• Line 6: Vary: Accept-Encoding is for shared caches: stores between you and the server that keep copies. It tells them this URL has a different copy for each format.

Compression makes text files like JavaScript smaller to send. But parsing still starts from the full, decompressed text.

Teams keep an eye on this with a bundle analyzer: a tool that lists every JavaScript file the build makes, with its size. Each file is called a chunk. A good habit looks like this:

1. List every chunk: the ones the page loads at the start, and the ones it loads later (lazy chunks).
2. Mark whether each chunk is needed for the current page.
3. Set a size limit, called a budget.
4. Stop a code change from being merged when it goes over the budget, unless the team agrees it's worth it.

A budget is easy to check with a few lines of code. A route is one page of an app with its own address, like /home or /shop. Here are two routes checked against one budget.

const budgetKb = 140;
const routes = [{ name: "home", initialKb: 132 }, { name: "shop", initialKb: 145 }];
for (const route of routes) {
  const result = route.initialKb <= budgetKb ? "within budget" : "over by " + (route.initialKb - budgetKb) + " KB";
  console.log(route.name + ": " + result);
}

Line 1 sets the budget: 140 KB. Line 2 lists two routes and how much JavaScript each one needs at the start. Lines 3 to 6 compare each route with the budget and print the result:

• The home route needs 132 KB, so it prints home: within budget.
• The shop route needs 145 KB, so it prints shop: over by 5 KB, because 145 − 140 = 5.

Your team picks these limits; the browser doesn't set them. It helps to track three separate limits:

• the JavaScript a route needs at the start,
• the biggest lazy chunk, which loads later,
• all of the route's JavaScript added together.

The next function checks all three. It is small, but it is real code that runs. It takes two things:

• a list of chunks. Each chunk has a compressed size, an uncompressed size, and initial: whether it loads at the start.
• a budget: the three limits, plus a guess of how fast a phone parses and compiles.

It adds up the sizes, guesses the parse and compile time, and reports exactly which limits failed. Press Step to watch it work.

1function checkJavaScriptBudget(chunks, budget) {2  const initialCompressedKb = chunks3    .filter((chunk) => chunk.initial)4    .reduce((total, chunk) => total + chunk.compressedKb, 0);5  const asyncCompressedKb = chunks6    .filter((chunk) => !chunk.initial)7    .reduce((total, chunk) => total + chunk.compressedKb, 0);8  const totalCompressedKb = chunks9    .reduce((total, chunk) => total + chunk.compressedKb, 0);10  const totalUncompressedKb = chunks11    .reduce((total, chunk) => total + chunk.uncompressedKb, 0);12  const overBudget = [];13 14  if (initialCompressedKb > budget.maxInitialCompressedKb) {15    overBudget.push({16      name: "initial total",17      overByKb: initialCompressedKb - budget.maxInitialCompressedKb,18    });19  }20 21  for (const chunk of chunks) {22    if (!chunk.initial && chunk.compressedKb > budget.maxAsyncChunkCompressedKb) {23      overBudget.push({24        name: chunk.name,25        overByKb: chunk.compressedKb - budget.maxAsyncChunkCompressedKb,26      });27    }28  }29 30  if (totalCompressedKb > budget.maxTotalCompressedKb) {31    overBudget.push({32      name: "total JavaScript",33      overByKb: totalCompressedKb - budget.maxTotalCompressedKb,34    });35  }36 37  return {38    initialCompressedKb,39    asyncCompressedKb,40    totalCompressedKb,41    estimatedParseCompileMs: Math.round(42      totalUncompressedKb * budget.mobileParseCompileMsPerKb,43    ),44    overBudget,45  };46}47 48const chunks = [Run49  { name: "app-shell", compressedKb: 82, uncompressedKb: 250, initial: true },50  { name: "product-route", compressedKb: 63, uncompressedKb: 210, initial: true },51  { name: "charting-library", compressedKb: 118, uncompressedKb: 410, initial: false },52];53 54const budget = {55  maxInitialCompressedKb: 140,56  maxAsyncChunkCompressedKb: 90,57  maxTotalCompressedKb: 260,58  mobileParseCompileMsPerKb: 0.2,59};60 61const report = checkJavaScriptBudget(chunks, budget);62console.log(63  "initial " + report.initialCompressedKb + " KB, async " + report.asyncCompressedKb + " KB",64);65console.log(66  "over budget: " + report.overBudget67    .map((item) => item.name + " +" + item.overByKb + " KB")68    .join("; "),69);70console.log("estimated parse/compile " + report.estimatedParseCompileMs + " ms");

1function checkJavaScriptBudget(chunks, budget) {2  const initialCompressedKb = chunks3    .filter((chunk) => chunk.initial)4    .reduce((total, chunk) => total + chunk.compressedKb, 0);5  const asyncCompressedKb = chunks6    .filter((chunk) => !chunk.initial)7    .reduce((total, chunk) => total + chunk.compressedKb, 0);8  const totalCompressedKb = chunks9    .reduce((total, chunk) => total + chunk.compressedKb, 0);10  const totalUncompressedKb = chunks11    .reduce((total, chunk) => total + chunk.uncompressedKb, 0);12  const overBudget = [];13 14  if (initialCompressedKb > budget.maxInitialCompressedKb) {15    overBudget.push({16      name: "initial total",17      overByKb: initialCompressedKb - budget.maxInitialCompressedKb,18    });19  }20 21  for (const chunk of chunks) {22    if (!chunk.initial && chunk.compressedKb > budget.maxAsyncChunkCompressedKb) {23      overBudget.push({24        name: chunk.name,25        overByKb: chunk.compressedKb - budget.maxAsyncChunkCompressedKb,26      });27    }28  }29 30  if (totalCompressedKb > budget.maxTotalCompressedKb) {31    overBudget.push({32      name: "total JavaScript",33      overByKb: totalCompressedKb - budget.maxTotalCompressedKb,34    });35  }36 37  return {38    initialCompressedKb,39    asyncCompressedKb,40    totalCompressedKb,41    estimatedParseCompileMs: Math.round(42      totalUncompressedKb * budget.mobileParseCompileMsPerKb,43    ),44    overBudget,45  };46}47 48const chunks = [49  { name: "app-shell", compressedKb: 82, uncompressedKb: 250, initial: true },50  { name: "product-route", compressedKb: 63, uncompressedKb: 210, initial: true },51  { name: "charting-library", compressedKb: 118, uncompressedKb: 410, initial: false },52];53 54const budget = {55  maxInitialCompressedKb: 140,56  maxAsyncChunkCompressedKb: 90,57  maxTotalCompressedKb: 260,58  mobileParseCompileMsPerKb: 0.2,59};60 61const report = checkJavaScriptBudget(chunks, budget);62console.log(63  "initial " + report.initialCompressedKb + " KB, async " + report.asyncCompressedKb + " KB",64);65console.log(66  "over budget: " + report.overBudget67    .map((item) => item.name + " +" + item.overByKb + " KB")68    .join("; "),69);70console.log("estimated parse/compile " + report.estimatedParseCompileMs + " ms");

Lines 1 to 46 are the checker. Line 48 lists three chunks: two load at the start, and the chart library loads later. Line 54 sets the limits: 140 KB at the start, 90 KB for any lazy chunk, and 260 KB in total. Line 61 runs the checker. Lines 62 to 70 print three lines:

• initial 145 KB, async 118 KB: 82 + 63 at the start, 118 later.
• over budget: initial total +5 KB; charting-library +28 KB; total JavaScript +3 KB: all three limits failed.
• estimated parse/compile 174 ms: 870 uncompressed KB × 0.2 ms per KB.

In a real project, you would feed this function from a file your bundler writes, which lists each chunk and its size. This site is built with Next.js, and each route has its own chunks. The sizes in this lesson are examples, not this site's real sizes.

Code splitting means breaking your JavaScript into several chunks, so a page downloads only what it needs. Route-level splitting gives each route its own chunk. Then the first page doesn't download the code for every other page.

Frameworks such as Next.js make one chunk per route by default. Bundlers also make a new chunk wherever they see import(). The question to ask is: does the user need this code for the first thing they do on the page?

1const button = document.querySelector("#load-chart");2const output = document.querySelector("#chart-output");3 4button.addEventListener("click", async () => {5  button.disabled = true;6  output.textContent = "Loading chart code...";7  try {8    const chart = await import("./chart.js");9    chart.renderChart(output);10  } catch {11    output.textContent = "Chart could not load. Try again.";12  } finally {13    button.disabled = false;14  }15});

Line 4 waits for a click on the button. Line 8 asks for the chart code: import() downloads chart.js and waits for it. Line 9 runs the loaded code, which writes the chart text. If the download fails, line 11 shows a message, and line 13 turns the button back on so the user can try again.

This is not the same as hiding work behind a timer. The browser doesn't even start to download chart.js until the click handler reaches import(). The dynamic import lesson explains the promise that import() returns and the module object it gives you.

Sometimes you want the opposite: the browser should start a download earlier than it would by itself. A resource hint is a <link> tag in the page that asks for that. Three hints look alike but do different jobs. Read each row as: "this hint asks for this, it helps this page, and watch out for this."

1<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>2<link rel="modulepreload" href="/assets/product-route.js">3<link rel="prefetch" href="/assets/settings-route.js" as="script">

Line 1 preloads a font this page needs soon; as="font" says what kind of file it is. Line 2 fetches the product route's module early, and the browser may fetch the modules it imports too. Line 3 fetches the settings route's script at low priority, in case the user goes there next.

Lazy loading works for images too. loading="lazy" tells the browser to wait before it downloads an image or an iframe, until the user scrolls near it. Use it for things below the fold: the part of the page you can't see without scrolling.

fetchpriority tells the browser how important a file is. Use high for the big main image at the top of the page, called the hero image. Use low for a product picture far down the page.

1<img2  src="/products/chair.webp"3  alt="Oak chair"4  width="640"5  height="480"6  loading="lazy"7  decoding="async"8  fetchpriority="low"9>10 11<img12  src="/hero.webp"13  alt="New dashboard preview"14  width="1280"15  height="720"16  fetchpriority="high"17>

Lines 1 to 9 are a chair photo far down the page. Line 6 makes it lazy. Line 7 lets the browser decode the image without making other content wait. Line 8 marks it low priority. Lines 11 to 17 are the hero image, and line 16 marks it high priority. Both images set width and height, so the browser can save space for them before they arrive.

The browser reads a page's HTML from top to bottom. The part that does this is the HTML parser. When the parser meets a <script> tag, the tag's attributes decide three things:

• Does the parser stop and wait for the script?
• Do the scripts run in the order they appear in the page?
• Does DOMContentLoaded wait for the script? This event fires once the parser has read all the HTML and the deferred scripts have run.

A classic script is a normal script, without type="module". MDN sums up the rules:

• An async classic script downloads while the parser keeps reading. It runs as soon as it arrives.
• A defer script downloads while the parser keeps reading. It runs after the parser finishes, and before DOMContentLoaded.
• A module script, type="module", acts like defer by default.
• A module script can also be async.

These rules come from the HTML specification; MDN explains them in easier words. The simulator below follows only these loading rules. It doesn't copy everything a real browser does, such as network priorities.

The table compares five kinds of script tag. Read each row as: "this script runs at this time, in this order, and DOMContentLoaded does or doesn't wait for it."

1<script src="legacy.js"></script>2<script src="analytics.js" async></script>3<script src="app.js" defer></script>4<script type="module" src="routes.js"></script>5<script type="module" async src="independent-widget.js"></script>

Line 1 is a classic script, so the parser stops for it. Line 2 is async. Line 3 is defer. Line 4 is a module, so it acts like defer. Line 5 is an async module.

CSS can hold up the page too. The browser usually won't draw (paint) the page until the stylesheets in the <head> have arrived and been read. So keep the CSS for the top of the page small, remove CSS you don't use, and don't make the hero wait for late styles.

The replay below runs a small simulator with four scripts: one of each kind. The parser alone would take 100 ms. Here is what the simulator finds:

1function simulateScriptTimeline(scripts, parserDuration = 100) {2  let parserDelay = 0;3  const events = [];4  const deferred = [];5 6  for (const script of scripts) {7    const discoveredAt = script.at + parserDelay;8    const readyAt = discoveredAt + script.downloadMs;9 10    if (script.kind !== "module" && !script.async && !script.defer) {11      events.push({ time: readyAt, label: "execute " + script.name });12      parserDelay += script.downloadMs + 1;13      continue;14    }15 16    if (script.async) {17      events.push({ time: readyAt, label: "execute " + script.name });18    } else {19      deferred.push({ ...script, discoveredAt });20    }21  }22 23  const parserDoneAt = parserDuration + parserDelay;24  let clock = parserDoneAt;25 26  for (const script of deferred) {27    const readyAt = script.discoveredAt + script.downloadMs;28    const startAt = Math.max(clock, readyAt);29    events.push({ time: startAt, label: "execute " + script.name });30    clock = startAt + 1;31  }32 33  events.sort((a, b) => a.time - b.time || a.label.localeCompare(b.label));34  return {35    executionOrder: events.map((event) => event.label.replace("execute ", "")),36    domContentLoadedAt: clock,37  };38}39 40const scripts = [Run41  { name: "analytics.js", at: 10, downloadMs: 70, async: true },42  { name: "vendor.js", at: 20, downloadMs: 40, defer: true },43  { name: "app.js", at: 30, downloadMs: 10, kind: "module" },44  { name: "legacy.js", at: 40, downloadMs: 20 },45];46 47const timeline = simulateScriptTimeline(scripts, 100);48console.log(timeline.executionOrder.join(" -> "));49console.log("DOMContentLoaded @" + timeline.domContentLoadedAt + "ms");

Press Step to see each rule at work. legacy.js holds the parser up for 21 ms, so parsing ends at 121 ms instead of 100 ms.

1<script src="dom-ready.js" defer></script>2<script src="feature.js" defer></script>

In the playground, pick a different attribute for feature.js. Watch the run order and the time of DOMContentLoaded change.

A fast first visit still matters. But on the next visit, the browser shouldn't have to do everything again. A cache is a place that keeps copies so they can be used again. Each kind of cache saves a different kind of repeat work:

• The browser's HTTP cache keeps downloaded files.
• Content-hashed file names, like app-shell.8f3a1c.js, make it safe to keep files for a long time.
• A CDN (content delivery network) keeps copies on servers close to users.
• A service worker, a script that sits between the page and the network, can answer requests from its own cache.
• The back/forward cache keeps a whole page ready for the Back and Forward buttons.
• V8 code caching keeps the compiled form of a script.

1Cache-Control: public, max-age=31536000, immutable2ETag: "app-shell.8f3a1c"3 4/assets/app-shell.8f3a1c.js  -> cache for a year5/assets/app-shell.91bd22.js  -> new URL after content changes

Line 1 tells the browser it may keep this file for a year (31,536,000 seconds), and that the file will never change (immutable). That is safe only because the file name has a content hash: a short code made from the file's content, like 8f3a1c. Line 4 is today's file. Line 5 is the file after a code change: new content, so a new hash and a new URL. Without the hash, users could be stuck with old JavaScript.

Line 2 is an ETag: a label for this exact version of the file. When the browser asks "has this changed?", the server can answer 304 Not Modified with no file attached. That saves bytes, but it still costs a request. A CDN makes each request travel a shorter way, because its servers are close to users. The browser's own cache is better still: it can skip many repeat requests completely.

1self.addEventListener("fetch", (event) => {2  const request = event.request;3 4  if (request.destination === "script") {5    event.respondWith(6      caches.open("static-v4").then(async (cache) => {7        const cached = await cache.match(request);8        if (cached) return cached;9        const response = await fetch(request);10        cache.put(request, response.clone());11        return response;12      }),13    );14  }15});

Line 1 listens for every request the page makes. Line 4 handles scripts only. Line 5 says the worker will answer this request itself. Lines 7 and 8 look for a saved copy and return it if there is one. If not, line 9 downloads the script, line 10 saves a copy, and line 11 returns it.

Service workers can make an app fast and even let it work offline. But they are a cache you program yourself, so you must also clean it up. The service workers lesson covers how a worker starts, which pages it controls, how to clean up, and offline fallbacks. The Cache API lesson explains that a named cache stores pairs of a Request and its Response. Unlike the HTTP cache, it doesn't throw old files away by itself.

The back/forward cache, or bfcache, keeps a whole snapshot of a page. When the user presses Back, the page comes back at once. Some code stops the browser from using it, like the first half of this example.

1// Avoid this pattern for analytics or cleanup.2window.addEventListener("unload", () => {3  navigator.sendBeacon("/analytics", "left page");4});5 6// Prefer signals that keep the back/forward cache available.7document.addEventListener("visibilitychange", () => {8  if (document.visibilityState === "hidden") {9    navigator.sendBeacon("/analytics", "hidden");10  }11});

Lines 2 to 4 listen for unload, the event that fires when the page is closed. A page-wide unload listener often stops the bfcache from working. Lines 7 to 11 do the same job with visibilitychange: when the page becomes hidden (line 8), line 9 sends the data. pagehide also works. Read the page lifecycle lesson before you add code that runs when the user leaves.

Core Web Vitals are three numbers that measure how a page feels to real users:

• LCP (Largest Contentful Paint): how long until the biggest thing on the first screen appears, often the hero image or the main heading.
• INP (Interaction to Next Paint): how long the page takes to show a response after a click, tap, or key press.
• CLS (Cumulative Layout Shift): how much the page jumps around while it loads.

They are field data: numbers measured on real users' devices, not in a test on your own computer. web.dev's Web Vitals guide, last updated on October 31, 2024, says a page is good when:

• LCP is 2.5 seconds or less,
• INP is 200 milliseconds or less,
• CLS is 0.1 or less.

They are checked at the 75th percentile: at least 75 out of every 100 page loads must meet the number. Mobile and desktop are checked separately.

The table shows how JavaScript can hurt each one. Read each row as: "this number is good at this level, and JavaScript can hurt it like this."

Many frameworks send HTML from the server, then run JavaScript in the browser to attach click handlers to it. That step is called hydration. With that word, here is how JavaScript hurts each number:

• LCP gets slower when JavaScript has to draw the hero, when the browser finds the hero image only after hydration, or when important CSS arrives late.
• INP gets slower when long hydration, big event handlers, or start-up work keep the main thread busy.
• CLS gets worse when JavaScript adds banners, ads, or other content after the page is laid out, without saving space for it.

PerformanceObserver is a browser tool that tells your code about performance events, such as the largest paint so far or a layout shift.

1const supported = "PerformanceObserver" in globalThis2  ? PerformanceObserver.supportedEntryTypes || []3  : [];4const watched = ["largest-contentful-paint", "layout-shift", "event"]5  .filter((type) => supported.includes(type));6 7console.log("Can watch: " + (watched.join(", ") || "none in this browser"));8 9if (watched.length > 0) {10  const observer = new PerformanceObserver((list) => {11    for (const entry of list.getEntries()) {12      console.log(entry.entryType + " @" + Math.round(entry.startTime));13    }14  });15  observer.observe({ type: watched[0], buffered: true });16  observer.disconnect();17}

Lines 1 to 3 ask which kinds of entry this browser supports. Lines 4 and 5 keep only the three this lesson cares about. Line 7 prints the ones this browser can watch. Line 10 makes an observer that prints each entry's type and time. Line 15 starts watching the first type; buffered: true also asks for entries from before. Line 16 stops watching straight away, because this is a quick demo. A real app keeps the observer running.

In real apps, many teams use the web-vitals library instead. It handles the differences between browsers and reports the final value of each number. It isn't installed on this site, so the next block can't run here.

1import { onCLS, onINP, onLCP } from "web-vitals";2 3onLCP((metric) => sendToAnalytics("LCP", metric.value));4onINP((metric) => sendToAnalytics("INP", metric.value));5onCLS((metric) => sendToAnalytics("CLS", metric.value));

Line 1 imports three functions. Lines 3 to 5 each give the library a function to call when a value is ready. sendToAnalytics stands for your own code that sends the number to your server.

Start every speed change by measuring. The measuring performance lesson shows how to time code, record traces in DevTools, and collect numbers from real users. The main thread lesson shows how long tasks make clicks feel slow. With those numbers, you can decide what to remove, split, preload, or cache. Here is a plan, step by step:

1. Open a bundle analyzer. List the chunks the slow route loads at the start, the ones it loads later, and the ones it shares with other routes.
2. Record a trace in the Performance panel with a slowed-down mobile setting. Check the time spent on parse, compile, execute, and hydration.
3. Set budgets: the compressed JavaScript at the start, the biggest lazy chunk, all of the route's JavaScript, and the length of long tasks.
4. Move code the user doesn't need at first to another route, or load it with import() when the user asks for it.
5. Give files that never change a content hash and a long cache time. Use a service worker only if you can also clean up its cache.
6. After the change goes live, check LCP, INP, and CLS in field data.

Common mix-ups

• "Only the gzip size matters." No. The download size matters, but parse, compile, memory, and execute all work on the full, uncompressed text.
• "Lazy loading always makes a page faster." No. It helps only when the code or image you delay isn't needed for what the user sees or does first.
• "async is better than defer." No. async is for scripts that don't depend on anything else. App code that needs page order usually wants defer or a module.
• "A green Lighthouse score means real users are fine." No. Lab tests help, but field data also includes slow phones, background tabs, and real networks.
• "Caching fixes too much JavaScript." No. Caching helps repeat visits. First visits, changed code, memory, and execute time still cost the same.

The table separates four terms that people often mix up. Read each row as: "this term means this, so use it for this."

Key takeaways

• A JavaScript file costs five jobs: download, decompress, parse, compile, and execute.
• Budgets should track the code at the start, the biggest lazy chunk, the total, and the CPU time.
• Split code by route, and use import() on a click, only for code the user doesn't need first.
• defer and module scripts keep page order; async is for scripts that don't depend on anything.
• The HTTP cache, service workers, V8 code caching, and the bfcache each save different repeat work.
• Check LCP, INP, and CLS with field data, at the 75th percentile.

Next in the Performance module: Finding memory leaks. There you will use heap snapshots, a list of everything in memory at one moment, to find what keeps old objects alive.