Top-level Await
In one line
Top-level await lets you use the await keyword at the top level of an ES module, without wrapping it in an async function.
In simple words
Top-level await allows you to use await at the top level of an ES module — outside any async function. Previously, await was only legal inside async functions, so you had to wrap module initialization in an async IIFE. Now you can await directly at module scope.
This is powerful for modules that need to do async work before they are ready: loading a config file, fetching initial data, importing a module dynamically. A module that uses top-level await blocks its dependents until it finishes — the importers wait for the awaited promise to resolve.
It is only allowed in ES modules (not CommonJS, not regular scripts). Use it for module initialization that genuinely must complete before the module is usable. Avoid long top-level awaits that block the whole app startup; prefer lazy loading for non-critical async work.
Example
// config.js (ES module)
const response = await fetch("/api/config");
export const config = await response.json();
// main.js
import { config } from "./config.js";
// main.js waits until config.js's top-level await resolves
console.log(config.apiUrl);The config module awaits fetch at the top level. Importers are blocked until it resolves, so config is ready when they run.
Related terms
Related Resources
Related Lessons
- Async Patterns
Learn top-level await.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.