ES modules in the browser

Ravi takes the bundler away

Ravi reads two guides on the same evening. Both are about how to send JavaScript to the browser. And they don't agree.

The first is the guide to importmap-rails, a tool for the Rails web framework. It says you can send many small files instead of one big one. It says that, thanks to HTTP/2, this "no longer carries a material performance penalty". In plain words: many files no longer cost much time. HTTP/2 is the version of HTTP that lets the browser ask for many files at once, over one connection. Lesson 4.5 showed it.

The second is the guide to Vite, a popular build tool. It says that sending files this way "is still inefficient due to additional network round trips from nested imports." A round trip is the time for a request to reach the server and for the answer to start coming back. In plain words: files that import other files cost extra trips.

Who is right? Ravi tries it on the tea list.

Until now, a bundler built the tea list. A bundler is a tool that joins many JavaScript files into one, like esbuild in lesson 22.2. Ravi takes it away. Now each file goes to the browser on its own, as a module: a JavaScript file that can import code from other files. Here is one of them:

1import { Price } from "./price.js";2import { StrengthBar } from "./strength-bar.js";3 4export function TeaCard({ tea }) {5  return (6    <li className={tea.sale ? "tea sale" : "tea"}>7      <a href="#">{tea.name}</a>8      <Price amount={tea.price} />9      <StrengthBar value={tea.strength} />10    </li>11  );12}

• Lines 1 and 2 import two more modules: price.js and strength-bar.js.
• Lines 4 to 12 draw one tea: its name, its price and its strength bar.

To draw a tea, the browser needs all three files. But it learns about price.js only by reading line 1 of tea-card.js. Remember that. This whole lesson grows from it.

Ravi still keeps one small build step. It turns each file's JSX, the HTML-like tags React uses, into plain JavaScript. It also gives each file a fingerprint: a short code made from the file's content, in its name. So tea-card.js is sent as tea-card-RKJUNIUU.js. Lesson 15.2 showed why: a file with a fingerprint can stay in the cache for a year. Then the build writes the top of the page:

1<script type="importmap">2{3  "imports": {4    "react": "./vendor/react-F2IRJJWW.js",5    "react/jsx-runtime": "./vendor/jsx-runtime-F7LXXYMP.js",6    "react-dom/client": "./vendor/react-dom-client-25HZSAN7.js",7    "./src/app.js": "./src/app-4KD5HBNT.js",8    …9    "./src/lib/money.js": "./src/lib/money-BNM4P4AD.js"10  }11}12</script>13<script type="module" src="./src/main-RLGB5T4Z.js"></script>

• Lines 1 to 12 are an import map. It tells the browser which file each name stands for.
• Lines 4 to 6 give a file to each of the three names the code uses for React. React comes from the shop's own server here.
• Line 7 sends ./src/app.js to the file with its fingerprint. Line 8 stands for 31 more lines like it. Line 9 is the last one, for money.js.
• Line 13 loads main.js, the first module. The browser finds all the others by itself.

The tea list has 39 modules: 34 of its own, and 5 of React's. React's three files share their code through two more files.

Then Asha opens the tea list on the bus. "Asha's phone" is the stand-in from lesson 22.1: Chrome 157 on a phone's screen, DevTools' Slow 4G network, and a CPU 4 times slower. The course loaded the tea list three ways, each with an empty cache:

• Native modules: Ravi's 39 modules, as above. Native means the browser loads them itself.
• With modulepreload: the same modules, plus one line in the page for each file. You'll meet it below.
• One bundle: the same code, joined by esbuild into one file, as before.

Here is what Asha saw:

At one second, all three showed the shop's name. The page's HTML is small, and it came about as fast each time. At 2.1 seconds, two of them showed the teas. The modules page made Asha wait until 4.9 seconds.

Here are the numbers. Read each row across: how the tea list was sent, its files, their size, then three moments.

• Sent with Brotli is the size after the server packs each file, as lesson 22.2 showed. A KB is 1,024 bytes.
• Teas on screen is when Chrome painted the tea list, the page's largest contentful paint.
• Could answer a tap is as in lesson 22.1. It's the later of two moments: the teas appearing, and the last long task ending. A long task keeps the phone busy for more than 50 ms.

Same code, same phone, same network. Without the bundler, the teas came 3.1 seconds later. With one line per file in the page, they came only 0.2 seconds after the bundle. Why it matters: dropping the bundler can cost a visitor seconds. But most of that cost can be won back.

The JavaScript lessons Module loading in browsers and Module resolution & import maps explain the rules inside. Here, you measure what they cost. The lesson follows Ravi's questions:

• Why did the modules page take so long? How the browser loads a module graph.
• Was it the number of files? Deep import chains.
• How did one line per file win it back? modulepreload for the whole graph.
• What does the import map do? Import maps.
• What happens when Asha comes back? Coming back, and a one-file change.
• So should Ravi bundle? When bundling still wins.

First, watch the three pages fill in. Move the slider:

How the browser loads a module graph

The tea list's modules import each other. Together they form a module graph: a map of which file imports which. main.js is at the top. It imports app.js and two of React's files. app.js imports the tea page. And so on, down to money.js, which imports nothing.

How does the browser walk that graph? The HTML standard spells it out. For each module, it does four things, in order:

1. It asks the server for the file.
2. It waits until the whole file has arrived.
3. It reads the file, and finds its import lines.
4. It asks for every file those lines name, unless it already has it.

Step 4 is step 1 again, one level down. So the browser can't ask for a file until the file that imports it has arrived. Here is the tea list's longest chain, from main.js down to money.js:

1// The modules page: when Chrome asked for each file on the way to money.js (ms).2const chain = [3  ["main.js", 608],4  ["app.js", 1185],5  ["teas-page.js", 1786],6  ["tea-list.js", 2362],7  ["tea-card.js", 2968],8  ["price.js", 3552],9  ["money.js", 4146],10];11for (const [file, asked] of chain) console.log(`${file}: asked for at ${asked} ms`);

• Lines 3 to 9 hold seven files. Each has the moment Chrome asked for it, in ms.
• Line 11 prints one line for each, from main.js: asked for at 608 ms to money.js: asked for at 4146 ms.

Each file was asked for about 590 ms after the one before. That's one round trip on Asha's network, plus the moment the file took to arrive. Lesson 22.4 showed that DevTools' Slow 4G adds 562.5 ms to every request. Seven files meant seven of those trips, one after another.

And while the files were arriving, nothing ran. The browser runs a module graph only once every module in it has arrived and been linked. Linking connects each import to the export it names. The JavaScript lesson Module loading in browsers walks through it.

1// The modules page: the last file, the first code, the teas (ms).2const moneyArrived = 4725;3const codeStarted = 4732;4const teasOnScreen = 4925;5 6console.log(`The code started ${codeStarted - moneyArrived} ms after money.js arrived.`);7console.log(`The teas came ${teasOnScreen - codeStarted} ms after that.`);

• Lines 2 to 4 hold three recorded times: when money.js arrived, when the page's code started, and when the teas appeared.
• Lines 6 and 7 print The code started 7 ms after money.js arrived. and The teas came 193 ms after that.

money.js is 42 bytes. It only writes a price, like £4.50. Yet the whole tea list waited for it.

Why it matters: on a modules page, the slowest level holds back everything. A tiny file deep in the graph can cost as much time as a big one.

Deep import chains

Was it the number of files that made the modules page slow? There were 39. Here is the graph level by level. A file's level is how many steps it is from the page. main.js is level 1. The files it imports are level 2, and so on.

1// The modules page, level by level: how many files, and when Chrome asked for the first (ms).2const levels = [3  [1, 608],4  [3, 1185],5  [3, 1773],6  [5, 2362],7  [24, 2968],8  [2, 3552],9  [1, 4146],10];11for (const [n, [files, asked]] of levels.entries())12  console.log(`Level ${n + 1}: ${files} ${files === 1 ? "file" : "files"}, first asked at ${asked} ms`);

• Lines 3 to 9 list seven levels. Each holds how many files it has, and when Chrome asked for the first of them.
• Line 11 goes through the list. Line 12 prints one line per level, from Level 1: 1 file, first asked at 608 ms to Level 7: 1 file, first asked at 4146 ms.

Look at line 7, level 5. It holds 24 files: tea-card.js and the 23 extras below the teas. Chrome asked for all 24 within 16 ms of each other. That's HTTP/2 at work: many requests at once, on one connection. And the next level began 584 ms after level 5 did. After level 1, which holds one file, the gap was 577 ms.

So the number of files cost little. The number of levels cost a lot. The time grows with the depth of the graph: the number of levels in its longest chain. It's like asking for directions in a town where each person knows only the next turn. Ten shops on one street don't slow you down. Ten turns do.

V8's guide to modules gives a simple rule. Native modules are fine in production only for small apps. That means "less than 100 modules in total", and "a maximum depth less than 5". The tea list has 39 modules, well under 100. But it's 7 levels deep.

Why it matters: keep import chains short. A helper that imports a helper that imports a helper adds a round trip each time. Try both pages, level by level:

modulepreload for the whole graph

The second page used modulepreload, the hint from lesson 16.4 and lesson 22.4. It tells the browser about a module before anything imports it. The HTML standard says it "places the result into the appropriate module map for later evaluation." The module map is the page's list of the modules it has loaded. A preloaded module waits there until something imports it.

Lesson 22.4 used it for two chunks. Ravi's build goes further. It writes one line for every module in the graph:

1<link rel="modulepreload" href="./src/main-RLGB5T4Z.js">2<link rel="modulepreload" href="./vendor/react-dom-client-25HZSAN7.js">3<link rel="modulepreload" href="./vendor/jsx-runtime-F7LXXYMP.js">4…5<link rel="modulepreload" href="./src/lib/money-BNM4P4AD.js">6<script type="module" src="./src/main-RLGB5T4Z.js"></script>

• Lines 1 to 3 are the first three modules, in level order: main.js, then two of React's files.
• Line 4 stands for 35 more lines. Line 5 is the last, for money.js.
• Line 6 is the module script, as before.

1// The modules page, without and with modulepreload (ms).2const without = { lastAsked: 4146, teas: 4925 };3const preloaded = { lastAsked: 631, teas: 2035 };4 5console.log(`The last file was asked for ${without.lastAsked - preloaded.lastAsked} ms sooner.`);6console.log(`The teas came ${without.teas - preloaded.teas} ms sooner.`);

• Line 2 holds two recorded times without modulepreload: when Chrome asked for the last file, and when the teas appeared. Line 3 holds the same two with it.
• Lines 5 and 6 print The last file was asked for 3515 ms sooner. and The teas came 2890 ms sooner.

With the list, Chrome asked for all 39 files within 9 ms of each other, right after the HTML. Seven rounds became one. The teas came at 2,035 ms, close to the bundle's 1,812 ms.

The list has costs of its own:

• The page grew. 39 lines made the HTML 2,555 bytes bigger, or 172 bytes with Brotli. Rolldown's guide warns that thousands of such lines are "a performance issue in itself."
• A tool has to write it. Every module must be on the list, and the list changes with every build. Ravi's build writes it from the graph.
• Chrome fetches only what's listed. The HTML standard lets a browser also fetch a preloaded module's imports, but doesn't make it. Chrome's own code fetches the one file and stops there. web.dev advises listing "the flat list of its dependencies".

Why it matters: if you ship native modules, list every module the page needs. It turns a staircase of trips into one.

Import maps: short names and fingerprints

Ravi's import map does two jobs. Both are about names.

Short names for React

The extras import React like this: import { useState } from "react". But "react" isn't an address. It's a bare name: no ./, no /, no https:. On its own, the browser can't load it. A bundler looks such names up in node_modules. The browser can't.

Line 4 of the import map fills the gap. The lesson Module resolution & import maps covers every rule. For speed, three facts matter:

• The import map sits inside the HTML. MDN says its src attribute "must not be specified", so it costs no request of its own.
• It must come before the module scripts that use it.
• It only changes addresses. Every file is still a request of its own.

Fingerprints in the map

The second job is about the cache. Say Ravi changes money.js. It gets a new fingerprint, so a new name. price.js imports it. If price.js named the file with its fingerprint, price.js would have to change too. Then tea-card.js, which imports price.js. And so on, all the way up to main.js.

Ravi's import lines keep the plain names, like ./price.js. The map holds the fingerprints. The HTML standard's own example maps /js/app.mjs to /js/app-8e0d62a03.mjs the same way. Here is Ravi's change:

// money.js, before the change:
export const money = (amount) => `£${amount}`;

// money.js, after it. The prices look the same.
const pounds = new Intl.NumberFormat("en-GB", { style: "currency", currency: "GBP" });

export const money = (amount) => pounds.format(Number(amount));

• Lines 1 and 2 are money.js before the change: the £ sign, then the amount.
• Lines 4 to 7 are money.js after it. It uses the browser's own number formatter. The prices look the same: £4.50.

1// Which files get a new name when money.js changes.2const inImportLines = ["money.js", "price.js", "tea-card.js", "tea-list.js", "teas-page.js", "app.js", "main.js"];3const inImportMap = ["money.js"];4 5console.log(`Fingerprints in the import lines: ${inImportLines.length} new files`);6console.log(`Fingerprints in the import map: ${inImportMap.length} new file`);

• Line 2 lists the files that would get new names if the fingerprints were in the import lines. Line 3 lists them with the fingerprints in the map.
• Lines 5 and 6 print Fingerprints in the import lines: 7 new files and Fingerprints in the import map: 1 new file.

Why it matters: with the fingerprints in the import map, a changed file changes alone. Rolldown's guide says bundlers can use import maps the same way.

Coming back, and a one-file change

V8's guide points to the other side. Native modules "might decrease initial load performance (cold cache), but could actually improve load performance for subsequent visits (warm cache)." A cold cache is an empty one, on a first visit. A warm cache already holds the files.

So the course had Asha come back. It loaded each page once, closed the tab and every connection, then loaded it again in a new tab. Every script now came from the disk cache. Only the page itself crossed the network, because the shop checks it on every visit.

1// Coming back, with every file in the cache: teas on screen (ms).2const modules = 897;3const bundle = 858;4 5console.log(`Modules: ${modules} ms. Bundle: ${bundle} ms.`);6console.log(`The difference: ${modules - bundle} ms.`);

• Lines 2 and 3 hold when the teas appeared on the second visit, in ms.
• Lines 5 and 6 print Modules: 897 ms. Bundle: 858 ms. and The difference: 39 ms.

The seven levels were still there. But each one now took a moment, not a round trip. With a warm cache, the depth hardly mattered.

Then Ravi published his change to money.js. Asha came back once more:

1// Coming back after the change to money.js: bytes downloaded, and teas on screen (ms).2const modules = { bytes: 1372, teas: 1509 };3const bundle = { bytes: 76660, teas: 1858 };4 5console.log(`Modules: ${modules.bytes} bytes, teas at ${modules.teas} ms`);6console.log(`Bundle: ${bundle.bytes} bytes, teas at ${bundle.teas} ms`);

• Lines 2 and 3 hold, for each page, the bytes that crossed the network and when the teas appeared.
• Lines 5 and 6 print Modules: 1372 bytes, teas at 1509 ms and Bundle: 76660 bytes, teas at 1858 ms.

On the modules page, two files crossed the network: the page, and the new money.js. The other 38 came from the cache. The bundle's name had changed too, because its content had. So Asha's phone downloaded all of it again, React included. It's lesson 15.2's ring binder: swap one page, instead of printing the whole book again.

Why it matters: if your visitors come back often, and you publish often, small files let a change cost only what changed. Pick each visit below. The page with modulepreload is there too:

When bundling still wins

So who was right? Here is every visit side by side. Read each row across: how the tea list was sent, when it could answer a tap on each visit, and what the change cost.

On the first visit, the bundle won. On the visit after a change, the modules won. With the cache full and no change, all three were within 50 ms. Three things kept the bundle ahead on the first visit.

It packs smaller

1// The tea list's JavaScript with Brotli, three ways (bytes).2const oneByOne = 91359;3const joinedFirst = 76963;4const bundled = 75956;5 6const kb = (bytes) => (bytes / 1024).toFixed(1);7console.log(`39 files packed one by one: ${kb(oneByOne)} KB`);8console.log(`The same 39 files joined, then packed: ${kb(joinedFirst)} KB`);9console.log(`The bundle: ${kb(bundled)} KB`);

• Lines 2 to 4 hold the tea list's JavaScript with Brotli: the 39 files packed one by one, the same 39 joined into one file before packing, and the bundle.
• Lines 7 to 9 print 39 files packed one by one: 89.2 KB, The same 39 files joined, then packed: 75.2 KB and The bundle: 74.2 KB.

Brotli finds repeats only inside one file, as lessons 22.2 and 22.4 showed. Joined first, the same code packed 14 KB smaller. The bundler saved 1 KB more, partly because it doesn't need the import and export lines between files.

It makes one request

The bundle is one request. The modules page made 39, in seven rounds. Even with modulepreload, the 39 files shared Asha's slow line. The last one arrived 236 ms after the bundle had. Rolldown's guide puts it plainly: "HTTP/2 does not mean you can stop caring about number of HTTP requests."

It needs a build step either way

Ravi didn't really drop his build. He still turned JSX into JavaScript, added fingerprints, and wrote the import map and the list. Rolldown's guide says Rails' own setup does the same. Its files "still go through a build step in order to fingerprint the assets and generate the import map and modulepreload directives."

The middle way is lesson 22.4's: a few chunks, the files a bundler splits the code into, each named in the page with modulepreload. Each chunk packs well, and a change re-sends only the chunk that holds it. web.dev's article on modulepreload says the same: "consider bundling your application into several chunks". V8's guide sums it up: "continue using bundlers before deploying modules to production."

Why it matters: bundle for first visits. Native modules suit small, shallow apps, pages people come back to often, and your own computer while you write the code.

Modules or a bundle?

Here are six places JavaScript ships. Sort each one by how its code should go out:

Common mix-ups

• "HTTP/2 makes many small files free." No. It asked for level 5's 24 files at once. But it couldn't skip the seven levels. The modules page showed the teas 3.1 seconds after the bundle.
• "A tiny module is quick to load." No. money.js is 42 bytes. Seven levels down, Chrome asked for it at 4,146 ms.
• "modulepreload on main.js fetches its imports too." No. The HTML standard allows it, but Chrome fetches only the file named. List every module.
• "An import map costs a request." No. It sits inside the HTML. It can't have a src.
• "Native modules send less code." No. Packed one by one, the tea list's 39 files were 15 KB bigger than the bundle.
• "A changed file always means one download." No. Only if the files that import it keep their names. With the fingerprints in the import lines, a change to money.js renames 7 files.

Practice exercises

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

// shop.js
import { cart } from "./cart.js";

// cart.js
import { tax } from "./tax.js";
import { money } from "./money.js";

// tax.js
import { rates } from "./rates.js";

Check your understanding

For each question, ask two things: when could the browser find the file, and did it have to cross the network?

Key takeaways

• The browser finds a module's imports only by reading it, so it loads a module graph one level at a time.
• Each level costs a round trip. The depth of the graph matters more than the number of files.
• A module graph runs only when every module has arrived. The deepest file holds back the whole page.
• One modulepreload line per module turns the levels into one round. Chrome fetches only what's listed.
• An import map gives bare names an address. Holding the fingerprints, it lets one change touch one file.
• One bundle won the first visit; native modules won the visit after a change. Bundle, or split into a few chunks.

Sources

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

• importmap-rails README (v2.2.3), Rails.
• Why Vite, Vite.
• Fetching scripts, HTML Living Standard, WHATWG.
• JavaScript modules, V8.
• Link type "modulepreload", HTML Living Standard, WHATWG.
• preload_helper.cc: what Chrome fetches for modulepreload (157.0.8103.52), Chromium source.
• Preload modules, web.dev.
• Import maps, HTML Living Standard, WHATWG.
• <script type="importmap">, MDN.
• Why do we still need bundlers?, Rolldown.

Coming next: The cost of hydration. The tea list's code now arrives fast. Next, what that code still has to do when the server has already drawn the page.