From HTML to running script

HTML arrives before JavaScript runs

A web page arrives as HTML text, a little at a time. The browser doesn't wait for all of it. It starts reading as soon as the first part arrives.

The part of the browser that reads HTML is called the HTML parser. Reading the HTML is called parsing. The parser turns the text into page elements, such as paragraphs and buttons.

A <script> tag can sit anywhere in that HTML. So a script may run before the whole page exists.

The tag itself decides when its code runs. These things change the timing:

• where the tag sits in the HTML;
• src, which names a separate file to download;
• the words async and defer on the tag;
• type="module" on the tag.

You'll meet each one in this lesson. For every script, keep three questions apart:

• Where has the parser got to?
• Has the script's file finished downloading?
• Is the script allowed to run yet?

These are different questions, even when the answers seem to come at the same moment.

This lesson continues from What happens when you navigate.

The HTML tokenizer and tree builder

The parser does its work in two parts:

• The tokenizer reads the HTML one character at a time. It cuts the text into pieces called tokens. A token is a start tag like <p>, some text, or an end tag like </p>.
• The tree builder takes the tokens one by one. It turns them into elements and puts each element inside its parent. The result is the document tree, also called the DOM.

Both parts work while the HTML is still arriving. The browser can make the first paragraph before the last part of the page arrives. That is why a script can find an element that comes earlier in the HTML.

The code below is a small model of these two parts. It is a teaching model written for this lesson, not the browser's real code. The lesson's setup code defines tokenizeTinyHtml and buildTinyTree for you.

const markup = "<p>Hi <b>there</b></p>";
const tokens = tokenizeTinyHtml(markup);
const tree = buildTinyTree(tokens);

console.log(tokens.map((token) => token.type).join(","));
console.log(tree.children[0].children.map((node) => node.name).join(","));

Line 1 stores a short piece of HTML. Line 2 cuts it into tokens, in the order they appear. Line 3 gives those tokens to the tree builder. Line 5 prints the kind of each token: start-tag,text,start-tag,text,end-tag,end-tag.

Line 6 prints "Hi ",b. These are the two things directly inside the paragraph: first the text, then the bold element b. The word there is inside b. So it is not directly inside the paragraph.

1const markup = "<p>Hi <b>there</b></p>";Run2const tokens = tokenizeTinyHtml(markup);3const tree = buildTinyTree(tokens);4 5console.log(tokens.map((token) => token.type).join(","));6console.log(tree.children[0].children.map((node) => node.name).join(","));

Browsers also fix broken HTML. In the code below, the first paragraph has no closing </p> tag. The model follows one real browser rule: a new <p> closes the paragraph that is still open.

const tree = buildRecoveringTree("<p>Tea<p>Cake");
const paragraphs = tree.children.filter((node) => node.name === "p");

console.log(paragraphs.length);
console.log(paragraphs.map((node) => node.children[0].name).join(","));

Line 1 leaves out the first closing tag on purpose. Line 2 picks out the paragraphs from the tree. Line 4 prints 2, and line 5 prints "Tea","Cake". Real browsers have many more rules like this one. The model shows only one.

Scripts that make the parser wait

Two words first:

• A classic script is a plain <script> tag, with no type="module".
• An inline script has its code written inside the tag, with no src file.

An inline classic script runs the moment the parser reaches it. It can find elements the parser has already built. It can't find elements that come later in the HTML.

<p>Hello</p><script>console.log(document.querySelectorAll("p").length)</script><p>World</p>

The parser reads the first paragraph before the script. The script calls querySelectorAll("p"), which finds every paragraph on the page so far. Only the first paragraph exists, so it prints 1. Then the parser carries on and builds the second paragraph.

A classic script with a src file follows the same rule, plus a download. The parser stops while the file downloads. Then it stops again while the script runs. This is called a parser-blocking script, because it blocks (stops) the parser.

A stylesheet can make the wait longer. The script might ask for the page's styles, so the browser may wait for the stylesheet before it runs the script.

The preload scanner looks ahead

While the parser is stopped, it can't see the tags further down the page. So the browser has a helper called the preload scanner. It skims ahead through the HTML text. When it sees a file address, it starts downloading that file early, before the parser gets there.

The preload scanner doesn't build elements. It never runs the page's JavaScript. It can only find addresses written plainly in the HTML, such as a stylesheet, an image, or a script's src.

<script src="/checkout.js" defer></script>

The address /checkout.js is written in the HTML, so the browser can start downloading it early. The defer on the tag still makes the script wait to run until all the HTML is read.

const html = '<script src="/app.js" defer></script>';
const injectedLater = 'document.createElement("script")';

console.log(html.includes("src=") ? "found early" : "not found");
console.log(injectedLater.includes("src=") ? "found early" : "created later");

Line 1 is HTML with a src in it, so line 4 prints found early. Line 2 stands for JavaScript that makes a script tag later, with document.createElement("script"). That text has no address in it, so line 5 prints created later.

The preload scanner can't find a script that doesn't exist yet. That script only appears when the JavaScript that makes it runs.

async, defer, and module scripts

Three choices change when a script runs. With all three, the file downloads while the parser keeps reading.

async runs the script as soon as its file has downloaded. This suits a script that no other script depends on. Two async scripts don't keep their written order. A later tag runs first if its file arrives first.

defer runs the script after the parser has read all the HTML. Deferred classic scripts run in the order they are written. So they suit files that must run in order, such as a cart file and then a checkout file.

A module script has type="module". It can use import to load other files. The browser downloads the module and every file it imports while the parser keeps reading. Without async, a module waits like defer. With async, it runs as soon as it and all its imports are ready.

An import map is a <script type="importmap"> tag. It tells the browser which file address to use for a short module name, such as "cart". Put it before the modules that use those names. It doesn't run any code itself.

const tags = [
  '<script src="/app.js"></script>',
  '<script src="/stats.js" async></script>',
  '<script src="/boot.js" defer></script>',
  '<script type="module" src="/main.js"></script>',
];

console.log(tags.length);
console.log("async runs when ready; defer waits for parsing");

Lines 1 to 6 make a list of four script tags:

• Line 2 is a plain classic script.
• Line 3 is a classic script with async.
• Line 4 is a classic script with defer.
• Line 5 is a module script.

Line 8 prints 4, the number of tags. Line 9 prints the main difference: async runs when ready, and defer waits for parsing.

Each row of the table below is one kind of script tag. Read it as: "this kind of tag treats the parser like this, and this decides its order."

Script execution order

No single rule decides the order scripts run in. Three things decide it together:

• where the parser has got to;
• which files have finished downloading;
• whether a script may run before parsing ends.

Real download times change from one visit to the next. So this lesson uses a small model where you set the times yourself. Each script has a kind and a downloadDoneAt number: the time its file finishes downloading.

In the model, parsing ends at time 3. Deferred scripts and modules run together, once parsing has ended and all of their files have downloaded. This is a teaching model, not the browser's real scheduler.

const scripts = [
  { name: "inline settings", kind: "inline", downloadDoneAt: 0 },
  { name: "checkout", kind: "async", downloadDoneAt: 2 },
  { name: "app", kind: "defer", downloadDoneAt: 5 },
  { name: "catalog", kind: "module", downloadDoneAt: 1 },
];

console.log(executionOrder(scripts).join(" -> "));

Lines 2 to 5 list four scripts, in the order they appear in the HTML:

• Line 2 is inline, so it runs in place.
• Line 3 is async. Its file is ready at time 2.
• Line 4 is deferred. Its file is ready at time 5.
• Line 5 is a module. Its file is ready at time 1, but it still waits for parsing.

Line 8 prints inline settings -> checkout -> app -> catalog. The inline script runs first, in place. The async script runs at time 2, as soon as it is ready. The deferred script and the module wait for parsing to end. Then they run in their written order.

1const scripts = [Run2  { name: "inline settings", kind: "inline", downloadDoneAt: 0 },3  { name: "checkout", kind: "async", downloadDoneAt: 2 },4  { name: "app", kind: "defer", downloadDoneAt: 5 },5  { name: "catalog", kind: "module", downloadDoneAt: 1 },6];7 8console.log(executionOrder(scripts).join(" -> "));

1const scripts = [2  { name: "inline settings", kind: "inline", downloadDoneAt: 0 },3  { name: "checkout", kind: "async", downloadDoneAt: 2 },4  { name: "app", kind: "defer", downloadDoneAt: 5 },5  { name: "catalog", kind: "module", downloadDoneAt: 1 },6];7 8console.log(executionOrder(scripts).join(" -> "));

In the playground, change the checkout download time from 2 to 9, then press Reset. At 9, checkout moves after the deferred script and the module. Those two stay in the same order. On a real network, download times change, so your app should never depend on the order of async scripts.

document.write writes into the HTML being read

document.write() adds HTML text straight into the HTML the parser is reading. Say an inline script calls it while the page is being read. Then the new HTML goes in at that exact spot. The parser reads it before the rest of the page.

Old pages used this to add ads or small pieces of HTML. But it breaks easily. The result depends on whether the browser is still reading the original page.

document.write("<p>Added while parsing</p>");
console.log("write was part of the current document stream");

This code only makes sense inside an inline script, while the page is being read. It isn't meant for the editor after the page has loaded. Line 1 adds a paragraph at the parser's current spot. Line 2 logs a note about that.

After the page has loaded, the parser is finished. Then document.write() starts a new, empty page that replaces the old one. In new code, add elements with DOM methods instead:

• document.createElement("p") makes a new element.
• textContent sets its text.
• append puts it inside a parent element you choose.

These steps work the same at any time, whether or not the parser is still running.

Fix a slow page's script tags

Use a parser-blocking classic script only when the script really must run at its exact spot in the HTML. Most startup code should use modules or deferred scripts. Then the parser can keep building the page while the files download.

Picture a shop page. The checkout code needs the cart code to run first. The two plain classic tags below stop the parser twice. Each download must finish before the parser can go on.

<script src="/cart.js"></script>
<script src="/checkout.js"></script>

Line 1 stops the parser until cart.js has downloaded and run. Then line 2 stops it again for checkout.js. The order is correct, but the parser sits idle during each download.

<script src="/cart.js" defer></script>
<script src="/checkout.js" defer></script>
<script src="/analytics.js" async></script>

Lines 1 and 2 now download while the parser keeps reading. They run after parsing, in order: cart, then checkout.

Line 3 loads analytics. Analytics code counts page visits, and no other script needs it. So async lets it run whenever its file is ready.

This change doesn't make a slow server faster. It removes waits the parser didn't need, and it shows clearly which script needs which. Measure the page after you change the tags. A tag only changes when a script runs. It doesn't make any file smaller.

Common mistakes about loading scripts

async changes when a script runs, not how fast it downloads. A file that downloads quickly runs sooner. But the word async doesn't make the file smaller or the server faster.

The preload scanner finds files to download. It doesn't run JavaScript. Deferred classic scripts keep their written order; async scripts don't. Module scripts without async wait for parsing and for every file they import.

• "Async is always faster." It only changes when the script may run.
• "Defer is async with a new name." Defer waits for parsing and keeps the written order.
• "The preload scanner runs code." It only finds files whose addresses are written in the HTML.
• "document.write adds elements like other DOM methods." It writes into the HTML being read, so its result depends on timing.

Each row of the table below is a word that is easy to mix up. Read it as: "this word means this, and it does not mean that."

Practice exercises

const before = ["Hello"];
console.log(before.length);

console.log(before.length); // 1

tokenizeTinyHtml("<p>Hi</p>").slice(0, 2);

const scripts = [
  { name: "first", kind: "async", downloadDoneAt: 3 },
  { name: "second", kind: "async", downloadDoneAt: 1 },
];
console.log(executionOrder(scripts).join(","));

console.log(executionOrder(scripts).join(",")); // second,first

const scripts = [
  { name: "app", kind: "defer", downloadDoneAt: 4 },
  { name: "catalog", kind: "module", downloadDoneAt: 1 },
];
console.log(executionOrder(scripts).join(","));

console.log(executionOrder(scripts).join(",")); // app,catalog

<script src="/analytics.js" async></script>

<script src="/cart.js" defer></script>
<script src="/checkout.js" defer></script>

Check your understanding

For each question, keep three things apart: where the parser is, which files are ready, and the written order. The questions use the same small models as the lesson.

Key takeaways

• The tokenizer cuts HTML into tokens. The tree builder turns them into elements while the HTML is still arriving.
• A classic script stops the parser at its spot in the HTML.
• The preload scanner finds file addresses written in the HTML and starts downloading them early. It never runs code.
• async runs a script when its file is ready. defer and modules without async wait for parsing.
• Before you change a script tag, work out which scripts need which.
• Avoid document.write in new code. Its result depends on whether the parser is still running.

Coming next: The rendering pipeline.