Top-level await & async evaluation

A module that waits

A module is a JavaScript file that uses import or export. Usually you can only write await inside an async function.

Top-level await means writing await directly in a module, outside any function. "Top level" means the outer part of the file.

It lets a module finish its setup before other files use it. A file that imports this module waits. Its own code starts only after the module is done.

A module graph is all the files of an app, joined by their import lines. An import line at the top of a file is called a static import. JavaScript runs an imported file first. Then it runs the file that imports it. Top-level await keeps this rule. The only change is that the imported file may take longer to finish.

This lesson uses small files, because the waiting depends on how the files import each other. The next lesson, Module loading in browsers, shows how the browser finds and downloads the files before any of them run.

A module with await runs in two parts

Start with one file, settings.js. It has three lines:

• Line 1 prints a message.
• Line 2 waits for a promise. A promise is a value that arrives later. This one already holds "dark".
• Line 3 prints a second message after the value has arrived.

console.log("settings start");
export const theme = await Promise.resolve("dark");
console.log("settings done");

Line 1 prints settings start. On line 2, await pauses the file until the promise gives its value, "dark". Then line 2 stores it in the exported name theme. Line 3 prints settings done.

Now a second file, main.js, imports theme. It does not need its own await. When its code starts, theme is already ready.

import { theme } from "./settings.js";
console.log("main sees", theme);

Line 1 imports theme from settings.js. Line 2 prints main sees dark. This line prints after both messages from settings.js.

The step-through below puts both files in one listing. Lines 1 to 3 are settings.js. Line 4 is the log from main.js.

1console.log("settings start");Run2const replayTheme = await Promise.resolve("dark");3console.log("settings done");4console.log("main sees", replayTheme);

Which modules wait

A module with top-level await waits for itself first. Then every file that imports it waits too. A file waits even if it imports the module through another file. So the waiting climbs up the graph, from the imported file to the files that import it.

The code below is a small model that works out which files wait. It is not the real code inside JavaScript. It keeps a list of waiting files. It adds a file to the list when that file imports a file that is already on the list.

function whoWaits(graph, asyncModules) {
  const waiting = new Set(asyncModules);
  let changed = true;
  while (changed) {
    changed = false;
    for (const [module, imports] of Object.entries(graph)) {
      if (imports.some((name) => waiting.has(name)) && !waiting.has(module)) {
        waiting.add(module);
        changed = true;
      }
    }
  }
  return [...waiting].sort();
}

const graph = {
  "main.js": ["settings.js", "logger.js"],
  "settings.js": [],
  "logger.js": [],
};
console.log(whoWaits(graph, ["settings.js"]).join(","));

In plain words, line by line:

• Line 2 makes a Set, a list with no repeats, called waiting. It starts with the file that has the await.
• Lines 4 and 5 repeat the search until a full pass adds no new file.
• Line 6 goes through every file and the list of files it imports. Object.entries gives each file name with its imports.
• Line 7 asks: does this file import a waiting file, and is it not on the list yet? .some is true if at least one import matches.
• Lines 8 and 9 add the file and note that the list changed.
• Line 13 returns the list in alphabetical order.
• Lines 16 to 20 describe the app: main.js imports settings.js and logger.js.

Line 21 prints main.js,settings.js. So main.js waits, and logger.js does not.

1function whoWaits(graph, asyncModules) {2  const waiting = new Set(asyncModules);Run3  let changed = true;4  while (changed) {5    changed = false;6    for (const [module, imports] of Object.entries(graph)) {7      if (imports.some((name) => waiting.has(name)) && !waiting.has(module)) {8        waiting.add(module);9        changed = true;10      }11    }12  }13  return [...waiting].sort();14}15 16const graph = {17  "main.js": ["settings.js", "logger.js"],18  "settings.js": [],19  "logger.js": [],20};21console.log(whoWaits(graph, ["settings.js"]).join(","));

Files that don't import it keep going

Two files imported by the same file are called siblings. The order of the import lines does not make one sibling wait for the other. Here main.js imports both settings.js and logger.js. But logger.js never imports settings.js.

// settings.js
console.log("settings start");
await Promise.resolve();
console.log("settings done");

// logger.js
console.log("logger runs");

// main.js
import "./settings.js";
import "./logger.js";
console.log("main runs");

The four lines always print in this order:

1. settings start (line 2)
2. logger runs (line 7)
3. settings done (line 4)
4. main runs (line 12)

settings.js pauses at its await on line 3. While it is paused, JavaScript runs logger.js.

This helps an app start faster. Setup files that don't need the waiting file can run in the meantime. But a file that imports the waiting file still waits for its exports.

A slow await holds up every file above it

A slow await in a file holds up every file that imports it, directly or through other files. That is useful when the app really cannot work before something is ready. Some examples:

• a setting every page needs,
• a connection to a server,
• a WebAssembly module, which is fast compiled code that JavaScript can load and call.

// config.js
console.log("config start");
await new Promise((done) => setTimeout(done, 20));
console.log("config done");

// app.js
import "./config.js";
console.log("app starts");

Line 3 waits for a short timer. setTimeout calls done after 20 milliseconds, and that ends the wait. The output is always in this order: config start, config done, then app starts. The exact delay can change from run to run. The order does not.

Sometimes only one feature needs the slow work. Then move the await into that feature, lower in the graph. The rest of the app can start without waiting for work the user may never ask for.

The table compares ways to get a module ready. Each row is one way. Read across to see where the waiting happens and which files are held up.

Try the waiting graph

The playground has one button. It switches the await in settings.js on or off. The results show:

• which files wait, from the model above,
• the order the four lines print, from the real three-file example.

Read the code first. Then press the button and compare both results. Reset turns the await back on.

1const graph = {2  "main.js": ["settings.js", "logger.js"],3  "settings.js": [],4  "logger.js": [],5};6 7const asyncModules = settingsUsesAwait ? ["settings.js"] : [];8console.log(whoWaits(graph, asyncModules).join(",") || "no modules wait");

When to use top-level await

Top-level await fits best when every file that imports a module needs it to be ready first. Two examples:

• a small config loaded once, which every page reads,
• a WebAssembly module that every importing file calls.

It also prevents a common bug. Some code starts setup inside an async function and calls it straight away, without await. Then another file can read an export before the setup is done. It gets a value that is not ready yet. With top-level await, JavaScript makes every importing file wait for the setup.

Keep the awaited work small and needed by everyone. Also plan for failure. If the promise fails (is rejected), the files that import the module don't run. So show the user a clear error when startup fails.

When to avoid top-level await

A library is shared code that many files import. Suppose a library awaits a slow network request at the top level. Then every file that imports it waits for that request when the app starts. That is a bad fit for work most users don't need, such as:

• extra data a page may never show,
• analytics, which records what users do,
• checkout code,
• a screen that many visitors never open.

There are two better choices:

• Use import() when a feature should load only when it is needed. import() is a function that loads a module when it is called and gives back a promise.
• Use an init() function when the calling code should decide when to start the setup. Then it can also show a loading message while it waits.

let configPromise;

export function loadConfig() {
  configPromise ??= fetch("/config.json").then((response) => response.json());
  return configPromise;
}

export async function startCheckout() {
  const config = await loadConfig();
  console.log("checkout uses", config.currency);
}

Line 4 starts a request for the config only when loadConfig() is called. The ??= operator stores the request only if configPromise is still empty. So a second call reuses the same request. Line 9 waits inside startCheckout(). So the rest of the app does not wait for checkout.

This example needs a web server that sends /config.json. That is why you can't run it in the editor here.

// The map styles start loading only when a map opens.
let stylesPromise;
export function init() {
  stylesPromise ??= Promise.resolve("loaded");
  return stylesPromise;
}
export async function openMap() {
  console.log("map styles", await init());
}
console.log("home page is already ready");
openMap();

Imagine the library awaited its map styles at the top level. Then even a login page that imports it would wait for map styles it never uses. Here, line 4 starts loading the styles only when someone calls init(). openMap() calls it on line 8.

Lines 10 and 11 show the result. home page is already ready prints first. Then map styles loaded prints. Two maps that both call init() still share one promise, so the styles load only once.

Top-level await is not bad. Use it when every file that imports a module needs the same thing to be ready. Keep optional work inside the feature that uses it.

Common mistakes

The word blocking can sound like the whole browser freezes. Here it means something smaller. A file that imports a waiting module does not run until that module is done. Files that don't import it can still run.

A static import line is not like a function call that runs at that exact spot. It only says which file this file needs. JavaScript first finds and connects all the files. Then it runs them, imported files first.

Each row of the table is a common belief. Read across to see what is really true and where this lesson shows it.

Practice exercises

Use the file names from the examples in your answers. The first exercises ask which files wait. The last ones ask what to choose in a small app.

console.log("settings start");

export async function init() { /* optional setup */ }

const checkout = await import("./checkout.js");

Quiz

The first questions check which files wait. The last ones check what to choose in a real app. For code questions, decide what prints before you pick an answer.

Key takeaways

• A module with top-level await pauses at that line. Files that import it wait until it is done.
• A file waits if it imports the waiting module, directly or through other files. The order of the import lines does not matter.
• Files that don't import the waiting module can run while it is paused.
• Use top-level await for setup that every importing file needs. Use import() or init() for optional work.

With top-level await, a module is ready only when its setup is done, and every file that imports it waits for that.

Coming next: Module loading in browsers.