Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Module Systems

Top-level await in Node.js

Reference for top-level await in Node.js ES modules: how it works, how it delays importing modules, why CommonJS cannot use it and how errors and hangs behave.

Top-level await lets an ES module use await directly in its body, outside any async function. The module then behaves like an async function that other modules wait for: a module that imports it does not start running until the awaiting module has finished.

It removes the old pattern of wrapping a whole program in (async () => { ... })(). Typical uses are loading configuration, opening a database connection, choosing an implementation with import(), or running a small script that needs several awaited steps. It works only in ES modules; in a CommonJS file await outside a function is a SyntaxError.

NODE
const response = JSON.parse(await readFile('config.json', 'utf8'));

Try it

Node.js Importers wait for the awaiting module

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Errors and where await is not allowed

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

How it works

A module that contains a top-level await is evaluated asynchronously. Node.js evaluates the module graph in dependency order, and when it meets such a module it pauses only the modules that depend on it. Independent branches (siblings that do not import each other) keep running, so one slow module does not stop its neighbours, as the first example shows.

If the awaited promise rejects and nothing catches it, the module fails to evaluate. Everything that imports it fails too, and for the entry file the process prints the error and exits with a non-zero code. If the promise never settles, the module never finishes. Node.js notices when the event loop is empty with an unfinished top-level await and exits with code 13 ("unsettled top-level await") and a warning.

Where it is available

Context Top-level await
.mjs file or "type": "module" Yes
.cjs file or CommonJS .js No: SyntaxError
-e / --eval with --input-type=module Yes
REPL Yes (Node.js adds support)
Inside a normal function or a callback Only with async
require() of an ES module that uses it No: ERR_REQUIRE_ASYNC_MODULE, use import()

Usage notes

  • Exports become available after the wait. Importers get a fully initialized module; they never see a half-ready export from a module with top-level await (except in circular imports).
  • Startup cost. Everything that imports the module is delayed by the awaited work, so keep slow awaits out of modules that many files import. Prefer exporting an async function and calling it where needed.
  • Use Promise.all for independent awaits at the top level; sequential awaits add up.
  • Errors need handling. Wrap risky calls in try/catch, or let the failure end the program with a clear message.
  • Cannot be used from CommonJS. Load such a module with import(). require(esm) throws for it.
  • Signals and event loop: the awaiting module does not block the event loop; timers, I/O and signal handlers keep working during the wait.
  • Exit code 13 means a top-level await was still pending when nothing else could wake the process, usually a promise whose resolve is never called.
  • Added in Node.js 14.8 (without a flag).