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.
const response = JSON.parse(await readFile('config.json', 'utf8'));
Try it
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.
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.allfor independent awaits at the top level; sequentialawaits 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
awaitwas still pending when nothing else could wake the process, usually a promise whoseresolveis never called. - Added in Node.js 14.8 (without a flag).