Script loading strategies

Meera adds a chat bubble

Meera wants two new things on the tea list at Leaf and Kettle. The first is a chat bubble, so customers can ask about a tea. The second is an analytics tag: a small script that counts visits, so she knows how many people come.

Each service sends a few lines to paste into the page. Both say the same thing: paste this in the head. So Ravi pastes them next to his own app. Here is the top of the tea list now, shortened:

1<head>2  <script>window.SHOP = { analytics: "LK-2041", chat: "leaf-and-kettle" };</script>3  <script src="app.js"></script>4  <script src="analytics.js"></script>5  <script src="chat-loader.js"></script>6</head>

• Line 2 is an inline script. Its code sits inside the tag, so there is no file to fetch. It sets a few settings that the other scripts read. We'll call it the config.
• Line 3 is app.js, Ravi's app. It holds React and the tea list, and draws the teas under the shop's name. Packed with Brotli, as the server sends it, it's 112.3 KB. That's about as much as the tea list's first load in lesson 22.6.
• Line 4 is analytics.js, the analytics tag.
• Line 5 is chat-loader.js. It doesn't hold the chat itself. It adds a second script, chat-widget.js, which does.

Lines 3 to 5 are classic scripts. A classic script is a plain script tag with a src, and no async, defer or type="module". The course wrote analytics.js and both chat files itself, so every run loads exactly the same code. They're small: the chat widget sends 16.9 KB.

Then Ravi reads three blog posts. One says: always use async. One says: always use defer. An older one says: put your scripts at the end of the body. Which one is right? Does it even matter, when the files are the same?

The course loaded the tea list six ways on Asha's phone. "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 four scripts never changed. Only their tags did. Here is app.js's tag on each page. The other two files were written the same way:

<script src="app.js"></script>               <!-- 1. in the head -->
<script src="app.js"></script>               <!-- 2. just before </body> -->
<script src="app.js" async></script>         <!-- 3. in the head -->
<script src="app.js" defer></script>         <!-- 4. in the head -->
<script src="app.js" type="module"></script> <!-- 5. in the head -->
<script src="loader.js" async></script>      <!-- 6. loader.js adds app.js -->

• Lines 1 to 5 load the same file five ways.
• Line 1 sits in the head. Line 2 sits at the very end of the body, just before </body>.
• Lines 3 to 5 each add one word. async means: run the file as soon as it arrives. defer means: run it once the whole HTML has been read. type="module" makes it a module, which also waits for the HTML.
• Line 6 is different. The HTML names only loader.js. When loader.js runs, it adds the other three tags itself.

Here is what Asha saw on each page, at three moments:

At one second, five pages showed the shop's name. The first page was still white. At 2.1 seconds, four pages showed the teas, and two still didn't. At 2.5 seconds, the page with loader.js was still waiting.

Here are the numbers behind the picture. Read each row across: how the tags were written, then three moments.

• First paint is the first moment anything appeared on the screen.
• Teas on screen is when Chrome painted the tea list. It's 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 appear, and the last long task ends. A long task keeps the phone busy for more than 50 ms.

Same files, same phone, same network. Yet the first paint came anywhere from 631 ms to 1,974 ms. The teas came anywhere from 2,000 ms to 2,809 ms. Why it matters: the way you write a script tag can cost a visitor more than a second, with no change to the code inside.

Running happens on the main thread. That's the one line of work where the browser runs scripts and draws the page. Only one thing happens on it at a time.

Lesson 5.3 met async, defer and modules, with one slow script. The JavaScript lesson From HTML to running script explains the rules behind them. This lesson puts all of them on one real page, and measures what each one costs. It follows Ravi's questions:

• In what order did the scripts run? Execution order for each kind.
• Is the end of the body as good as defer? The head or the end of the body.
• Why does chat-widget.js always come late? Scripts added by other scripts.
• What does an inline script cost? Inline scripts.

First, see the six pages fill in. Move the slider, and watch each page change:

When each kind of script runs

Start with the order. On every page, the same five pieces of code ran: the config, app.js, analytics.js, chat-loader.js and chat-widget.js. But they didn't run in the same order. Here are two of the pages:

1// The order the scripts ran in, on two of the six pages.2const asyncPage = ["config", "analytics.js", "chat-loader.js", "app.js", "chat-widget.js"];3const deferPage = ["config", "app.js", "analytics.js", "chat-loader.js", "chat-widget.js"];4 5console.log(`async: ${asyncPage.join(", ")}`);6console.log(`defer: ${deferPage.join(", ")}`);

• Line 2 lists the async page's scripts, in the order they ran. Line 3 does the same for the defer page.
• Line 5 prints async: config, analytics.js, chat-loader.js, app.js, chat-widget.js.
• Line 6 prints defer: config, app.js, analytics.js, chat-loader.js, chat-widget.js.

Both pages ran the config first. It's inline, so it ran the moment the parser reached it. The parser is the part of the browser that reads the HTML from top to bottom. After the config, the two orders split.

async: in the order the files arrive

1// The async page: when each file had arrived, and when it ran (ms).2const files = [3  ["analytics.js", 1187, 1188],4  ["chat-loader.js", 1194, 1195],5  ["app.js", 1905, 1909],6];7for (const [file, arrived, ran] of files) console.log(`${file}: arrived at ${arrived}, ran at ${ran}`);

• Lines 2 to 6 list three files: when each had arrived, and when it ran, in ms.
• Line 7 prints one line for each: analytics.js: arrived at 1187, ran at 1188, chat-loader.js: arrived at 1194, ran at 1195 and app.js: arrived at 1905, ran at 1909.

Each file ran within a few ms of arriving. analytics.js is only 161 bytes with Brotli, so it came first, and ran first. app.js is 112.3 KB, so it came last. The order of the tags didn't matter at all. Why it matters: never give async to a script that needs another script to run first. On another visit, the files could arrive in another order.

defer: in the order of the tags

1// The defer page: when each file had arrived, and when it ran (ms).2const files = [3  ["app.js", 1833, 1838],4  ["analytics.js", 1192, 1937],5  ["chat-loader.js", 1203, 1939],6];7for (const [file, arrived, ran] of files) console.log(`${file}: waited ${ran - arrived} ms to run`);

• Lines 2 to 6 list the same three files on the defer page.
• Line 7 prints how long each one waited between arriving and running.
• It prints app.js: waited 5 ms to run, analytics.js: waited 745 ms to run and chat-loader.js: waited 736 ms to run.

The two small files arrived at about 1.2 seconds. Then they waited, because app.js comes first in the HTML, and it hadn't arrived yet. Deferred scripts run after the whole HTML has been read, in the order of their tags. So the defer page ran its scripts in the order Ravi wrote them. Why it matters: defer is the choice when one script needs another, like a cart script that uses app.js.

The module page ran in exactly the same order as the defer page. A module script is deferred unless it has async. The next lesson looks at what else modules change.

DOMContentLoaded and the load event

DOMContentLoaded is the event the browser fires once it has read all the HTML. Lesson 5.3 showed that it waits for deferred scripts. Here is what that meant for the tea list:

1// When DOMContentLoaded and the load event fired (ms).2const asyncPage = { domContentLoaded: 616, load: 2225 };3const deferPage = { domContentLoaded: 1940, load: 2768 };4 5console.log(`async: DOMContentLoaded at ${asyncPage.domContentLoaded}, load at ${asyncPage.load}`);6console.log(`defer: DOMContentLoaded at ${deferPage.domContentLoaded}, load at ${deferPage.load}`);

• Line 2 holds the async page's two times. Line 3 holds the defer page's.
• Lines 5 and 6 print async: DOMContentLoaded at 616, load at 2225 and defer: DOMContentLoaded at 1940, load at 2768.

On the async page, DOMContentLoaded fired at 616 ms, right after the HTML was read. It doesn't wait for async scripts. On the defer page, it waited 1.3 seconds more, for app.js and the two small files.

The load event is different. It fires when the page and its files have finished loading. On both pages, it came after chat-widget.js had run. The HTML standard says why. Before it fires load, the browser waits for every async script, and every script added by another script, that is still on its way.

Why it matters: code that waits for DOMContentLoaded starts at very different moments. It depends on how the page's other scripts are written.

A script that may run early or late

Here's a puzzle. On the first page, app.js ran in the head, before the body existed. Its <div id="root"> wasn't there yet. So how did it draw the teas? Its last three lines start the app:

const start = () => createRoot(document.getElementById("root")).render(<App />);
if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start);
else start();

• Line 1 makes a function, start, that draws the tea list into #root.
• Line 2 checks document.readyState. The value "loading" means the HTML is still being read. Then the app waits for DOMContentLoaded.
• Line 3 starts at once, because the HTML has already been read.

MDN's page on DOMContentLoaded gives this pattern. It's for scripts that can't know how they'll be loaded. The chat widget does the same. Why it matters: a script that might run before the HTML is read must wait for the elements it needs.

Now look at every page, script by script. Pick a page:

In the head, or at the end of the body

Now the old advice: put scripts at the end of the body. Was it right? Compare the first two pages. Both use classic scripts. Only the place of the tags differs:

1// app.js as a classic script: in the head, and at the end of the body (ms).2const head = { asked: 605, firstPaint: 1974, teas: 2044 };3const body = { asked: 598, firstPaint: 632, teas: 2062 };4 5console.log(`Chrome asked for app.js at ${head.asked} and ${body.asked}`);6console.log(`First paint at ${head.firstPaint} and ${body.firstPaint}`);7console.log(`Teas on screen at ${head.teas} and ${body.teas}`);

• Line 2 holds three times from the page with the tags in the head. Line 3 holds the same three from the end of the body.
• Lines 5 to 7 print Chrome asked for app.js at 605 and 598, First paint at 1974 and 632 and Teas on screen at 2044 and 2062.

Chrome asked for app.js at almost the same moment on both pages. That's the preload scanner from lesson 5.2: a second reader that skims ahead and starts fetching every file it finds. The teas also came at almost the same time, about 2 seconds. The big difference was the first paint: 1,342 ms.

In the head, the parser stopped before it reached the body. There was nothing to paint yet. And the HTML standard counts a classic script in the head as render-blocking: the browser won't paint until it has run. At the end of the body, the parser had already built the header. Chrome painted it while the parser waited.

So the end of the body helps the first paint. Does it beat defer? On this page, no. The two were almost the same: first paint at 632 and 647 ms, teas at 2,062 and 2,004 ms. And two things keep defer ahead on real pages:

• A long page arrives in pieces. The preload scanner can only read the pieces that have arrived. A tag at the very end is found with the last piece. A tag in the head is found with the first. The tea list's HTML is small, so it arrived in one go.
• A classic script at the end of the body still stops the parser. DOMContentLoaded waited until 1,972 ms, about as long as with defer.

The priority Chrome gave each one

When Chrome asks for a file, it gives the request a priority: how urgent it is, next to the page's other requests. Lesson 5.4 showed how it picks one. Here is where app.js started on five pages:

1// The priority Chrome gave app.js when it asked for it, as DevTools names it.2const priority = {3  "classic, head": "High",4  "classic, body": "High",5  async: "Low",6  defer: "Low",7  "added by loader.js": "Low",8};9for (const [page, name] of Object.entries(priority)) console.log(`${page}: ${name}`);

• Lines 2 to 8 hold the priority Chrome gave app.js on five pages, in DevTools' names.
• Line 9 prints one line for each, from classic, head: High to added by loader.js: Low.

Classic scripts started High, because the parser waits for them. async, defer and added scripts started Low. Chromium's own source says so, in a comment: "Async/Defer: Low Priority". The same file starts a classic script at Medium if the preload scanner finds it after the page's first picture. The tea list has no picture above its scripts. Module scripts aren't classic, so app.js started High on the module page.

On this page, priority changed little. app.js started High on the classic and module pages, and Low on the defer page. Yet it arrived between 1,818 and 1,833 ms on all four. On a page with many files fighting for the network, it matters more.

Why it matters: put scripts in the head, with defer. The browser finds them in the first piece of HTML, and the first paint doesn't wait for them.

Scripts added by other scripts

One file was late on every page: chat-widget.js. Here is chat-loader.js, the snippet the chat service gave Meera:

1// chat-loader.js: adds the chat widget to the page.2const script = document.createElement("script");3script.src = "chat-widget.js";4script.dataset.team = window.SHOP.chat;5document.head.append(script);

• Line 2 makes a new script element. Line 3 names the file it should load.
• Line 4 passes on the shop's chat name, from the config.
• Line 5 adds the element to the head. Only now does Chrome ask for the file.

A script that another script adds to the page is called an injected script. The preload scanner can't see it. It reads the HTML, and the HTML never names chat-widget.js. Chrome only learns about the file when line 5 runs:

1// When chat-loader.js ran, and when Chrome asked for chat-widget.js (ms).2const pages = [3  ["classic, head", 1943, 1943],4  ["async", 1195, 1196],5  ["defer", 1939, 1939],6];7for (const [page, ran, asked] of pages) console.log(`${page}: loader ran at ${ran}, widget asked for at ${asked}`);

• Lines 2 to 6 hold two times for three pages: when chat-loader.js ran, and when Chrome asked for chat-widget.js.
• Line 7 prints one line for each page. The first is classic, head: loader ran at 1943, widget asked for at 1943.
• Then async: loader ran at 1195, widget asked for at 1196 and defer: loader ran at 1939, widget asked for at 1939.

On every page, the request left the moment the loader ran, never sooner. On the defer page, chat-loader.js had arrived at 1,203 ms. But it waited in line behind app.js. So the widget was asked for 736 ms after its loader had arrived.

A page where every script is added

The sixth page went further. Its HTML named only loader.js:

1// loader.js: adds the page's three scripts.2for (const file of ["app.js", "analytics.js", "chat-loader.js"]) {3  const script = document.createElement("script");4  script.src = file;5  document.head.append(script);6}

• Line 2 goes through the three files. Lines 3 and 4 make a script element for each one.
• Line 5 adds it to the head.

Every file now needed one more trip on the network before Chrome could even ask for it:

1// app.js written in the HTML with async, or added by loader.js (ms).2const written = { asked: 606, teas: 2228 };3const added = { asked: 1180, teas: 2809 };4 5console.log(`Added: asked for ${added.asked - written.asked} ms later`);6console.log(`Added: teas on screen ${added.teas - written.teas} ms later`);

• Line 2 holds app.js written in the HTML with async. Line 3 holds app.js added by loader.js.
• Lines 5 and 6 print Added: asked for 574 ms later and Added: teas on screen 581 ms later.

Chrome couldn't ask for app.js until loader.js had arrived and run. That cost a whole extra trip on Slow 4G. The teas appeared at 2,809 ms, the latest of all six pages.

Added scripts also behave like async ones. The HTML standard gives every script element a hidden flag called force async. It starts as true, and the parser turns it off for the tags it reads from the HTML. A script made by a script keeps it. So the three files ran in the order they arrived: analytics.js, chat-loader.js, then app.js. And Chrome gave each one Low.

web.dev's article on the preload scanner sums it up: "if a script is needed during startup, don't defeat the preload scanner by injecting it into the DOM." For the chat, lesson 19.2 had another answer: a facade, which loads the widget's code only when someone taps the bubble.

Why it matters: write the tags of the scripts the page needs in the HTML. Leave adding scripts with code for the ones that can come late.

Inline scripts

The config, on line 2 of the head, is inline. It cost nothing to fetch, because its code came inside the HTML. It took a millisecond or less to run. Inline scripts are good for small jobs like that.

But an inline script runs right where the parser meets it, and the parser waits while it runs. A week later, Meera tries an offers tool. Its instructions say: paste this inline, at the top of the head, so the offer is ready early. Ravi pastes it on the defer page. The loop stands in for the tool's real work:

1<script>2// The offers tool: score each of 300 teas against its past sales.3let best = 0;4let bestScore = -1;5for (let tea = 0; tea < 300; tea++) {6  let score = 0;7  for (let sale = 0; sale < 30000; sale++) score = (score * 31 + tea + sale) % 1000003;8  if (score > bestScore) [best, bestScore] = [tea, score];9}10window.SHOP.offer = best;11</script>

• Lines 1 and 11 make it an inline script.
• Lines 3 and 4 keep the best tea so far, and its score.
• Lines 5 to 9 go through 300 teas. Line 7 scores each one against 30,000 made-up sales.
• Line 10 saves the winner in the config, for app.js to show.

1// The defer page, without and with the offers tool's inline script (ms).2const without = { firstPaint: 647, teas: 2004 };3const inline = { firstPaint: 853, teas: 2013 };4 5console.log(`First paint: ${inline.firstPaint - without.firstPaint} ms later`);6console.log(`Teas on screen: ${inline.teas - without.teas} ms later`);

• Line 2 holds two times from the defer page without the offers tool. Line 3 holds the same two with it.
• Lines 5 and 6 print First paint: 206 ms later and Teas on screen: 9 ms later.

The offers tool kept the phone busy for 209 ms, from the moment the HTML arrived. Asha's screen stayed white the whole time. The teas hardly moved, because app.js was still downloading anyway. And Chrome had already asked for app.js, at 596 ms, before the tool ran. The preload scanner had found it.

How do you move inline work later? Here are two ways to write the tag:

<script defer>/* the same offers code */</script>
<script type="module">/* the same offers code */</script>

• Line 1 adds defer. The HTML standard doesn't allow defer on an inline script, and browsers ignore it there. MDN says "it would have no effect". The script runs during parsing, just as before.
• Line 2 makes it a module. An inline module script is deferred, like one with a file. It runs after the HTML has been read.

As a module, the first paint came at 656 ms, about as early as on the page without the tool. The tool's 209 ms ran once the HTML had been read, while app.js was still on its way. The teas came at 2,013 ms. Here are the two ways side by side:

One more cost. A plain inline script that comes after a stylesheet waits for that stylesheet. MDN's page on DOMContentLoaded says scripts that aren't deferred or async "will wait for already-parsed stylesheets to load". The tea list's styles are inline, so nothing made the config wait.

Compare all four versions of the page, including the one with defer:

Why it matters: keep inline scripts small. If one must do heavy work, make it a module, or move the work into a file with defer.

A way for every script

Here is everything the pages showed, in one table. Read each row across: the tag, whether the preload scanner can find it, the priority Chrome started app.js at, when it runs, and whether DOMContentLoaded waits for it.

web.dev gives a simple rule for scripts from other companies: always load them with async or defer, "unless the script has to run before the page can be rendered". Use defer when a script needs the page or another script. Use async for a script that stands alone. Keep a plain script only for a tiny job the first paint needs, and make it inline. And if one script must arrive sooner than the others, fetchpriority="high" works on script tags too.

Now sort these scripts. Which way should each one load?

Common mix-ups

• "Scripts at the end of the body are fetched late." No. The preload scanner finds them as soon as that part of the HTML arrives. On the tea list, Chrome asked for app.js at 598 ms there, and at 605 ms in the head.
• "async is always faster than defer." No. On the async page, the teas came 224 ms later than on the defer page, because the chat widget ran before they were painted.
• "defer on an inline script runs it later." No. Browsers ignore defer on a script with no src. Use type="module" instead.
• "DOMContentLoaded means the page's scripts have run." No. It doesn't wait for async or added scripts. On the async page, it fired at 616 ms, before any of them had run.
• "A script added with createElement runs where it was added." No. It runs as soon as its file arrives, like an async script.
• "Inline scripts are free, because there's nothing to download." No. They run on the main thread while the parser waits. The offers tool held the first paint back 206 ms.

Practice exercises

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

<script src="reviews.js" async></script>  <!-- arrives at 900 ms -->
<script src="stars.js" async></script>    <!-- arrives at 400 ms -->

// loader.js: adds the page's three scripts.
for (const file of ["app.js", "analytics.js", "chat-loader.js"]) {
  const script = document.createElement("script");
  script.src = file;
  // Your line here
  document.head.append(script);
}

script.async = false;

Check your understanding

For each question, ask two things: when was the file asked for, and when did it run?

Key takeaways

• A script tag decides when the file is asked for and when it runs. Asking early is cheap. Running makes the page wait.
• Classic scripts run in place and stop the parser. In the head, they kept Asha's screen white until 1,974 ms.
• async scripts run as they arrive, in any order. defer and module scripts run in the order of their tags, after the HTML is read.
• DOMContentLoaded waits for defer and module scripts. The load event waits for async and added scripts.
• Added scripts are hidden from the preload scanner, start Low, and act like async ones. Each costs one more trip.
• Inline scripts cost no request, but run while the parser waits. type="module" moves their work after the first paint. defer doesn't.

Sources

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

• The script element, HTML Living Standard, WHATWG.
• The end: what happens after parsing, HTML Living Standard, WHATWG.
• Document: DOMContentLoaded event, MDN.
• Render-blocking mechanism, HTML Living Standard, WHATWG.
• resource_fetcher.cc: how Chrome picks a request's priority (157.0.8103.52), Chromium source.
• script_loader.cc: which scripts load as Low (157.0.8103.52), Chromium source.
• Don't fight the browser preload scanner, web.dev.
• <script>: The Script element, MDN.
• Efficiently load third-party JavaScript, web.dev.
• HTML attribute: fetchpriority, MDN.

Coming next: ES modules in the browser. The tea list's scripts now load in the right order. Next, what happens when the browser loads a whole tree of modules itself.