async-await
Top-level await
Allows using await outside of any async function at the top level of an ECMAScript module. The module's evaluation waits for the awaited promise, blocking importers until it settles.
await expression // at module top levelParameters
| Parameter | Purpose |
|---|---|
| ES modules only | Requires type="module" or .mjs — not allowed in CommonJS or scripts |
| blocks importers | Modules importing this one wait for its top-level awaits to settle |
| runtime | Node 14.8+ (ESM), modern browsers, bundlers via ES2022 target |
Examples
// config.mjs
const res = await fetch('/config.json');
export const config = await res.json();The exported config is ready-to-use by importers — no async wrapper needed.
// dynamic import at module scope
const { default: heavy } = await import('./heavy-module.mjs');Lets a module conditionally load dependencies before exporting.
// Fails in a classic script
<script>await fetch('/x'); // SyntaxError</script>
<script type="module">await fetch('/x'); // OK</script>Only works with type="module" scripts and .mjs files.
Gotcha
Top-level await delays every importer — a slow await can stall your whole app's startup. It is a SyntaxError in CommonJS and classic