When is top-level await in an ES module the right way to do async initialization, and when would you instead export an initializer function or a promise?

## What the decision is really about Both designs solve the same problem — a module needs something asynchronous before it is useful — and they differ in *who* is forced to wait and *where* a failure surfaces. Top-level await moves both concerns into the module system. The importer cannot proceed until the value exists, so the ordering is guaranteed by the language rather than by discipline. An exported initializer or promise moves both concerns into user code: the module loads instantly, and each consumer decides when to await and what to do if it fails. ## The case for top-level await It is the right tool when three things are true at once. First, the module's export is genuinely meaningless before the async step. A module that exists to provide a parsed configuration object, an instantiated WebAssembly export table, or a driver selected at load time has nothing sensible to expose in the meantime. Exporting a placeholder would just invite someone to read it too early. Second, essentially every consumer needs the value. If the module is only imported by the handful of places that use the value, the delay is not being imposed on anyone who does not benefit from it. Third, a failure genuinely should stop the program. If the app cannot function without the value, then failing the load loudly is better than starting up in a broken state. When those hold, top-level await removes an entire class of bugs by construction. The alternative in this situation is a convention — "always await `ready` before touching anything" — and conventions are exactly what a new contributor breaks in month three, with a failure that is intermittent and hard to reproduce. ```javascript // runtime.js — the export has no meaningful value before this completes export const runtime = await instantiateRuntime(); ``` ## The case against it The costs are all consequences of one fact: the module system, not the caller, owns the waiting and the failure. **Latency propagates to the whole ancestor chain.** Anything that imports this module, transitively up to the entry point, starts later. If the module sits on a hot import path — a utility, a logger, a shared constants file — one await can dominate time-to-first-work for code that never touches the awaited value. **Failures cannot be handled by static importers.** There is no place to write a `catch` around a static `import`, so a rejected top-level await takes down the load of everything above it. If you want a fallback, a retry with backoff, a timeout, or degraded operation, the awaited work must be under a caller's control, not part of evaluation. **Consumption becomes asynchronous-only.** A module whose graph contains a top-level await cannot be loaded synchronously; runtimes that otherwise permit synchronous consumption of ES modules refuse when the graph is async, and non-ESM output formats cannot express a module that suspends. For a published library, this narrows who can consume you. **It interacts badly with cycles.** If the module ends up in an import cycle, a top-level await can produce a load that hangs with no error at all — the least diagnosable failure in this area. ## What the alternatives give up and gain An exported `async` initializer (`export async function init()`) gives callers total control: they choose when to run it, can retry or time out, can supply configuration, and can decide what a failure means. The price is that the module now has a lifecycle that consumers must respect, and nothing prevents a consumer from using it before `init()` resolves. That has to be defended against — throwing a clear error from accessors before initialization is the usual approach, and a clear error beats a silent placeholder. An exported promise (`export const ready = load()`) is a middle position: the work starts at module load, so it overlaps with everything else, but consumers await it at the point of use rather than at the point of import. Nothing is blocked, and each consumer can catch the rejection. The cost is that the promise is a shared object whose rejection needs handling somewhere, and the discipline of awaiting it is once again a convention. Lazy initialization inside an accessor — start the work on first use and memoize the promise — costs nothing at startup and is the natural fit for something only some code paths need. ## How I would decide Start from the import fan-in. A module imported by three call sites that all need the value is a fine candidate for top-level await. A module imported by two hundred files is not, regardless of how convenient the ergonomics look. Then ask whether the operation can fail in a way you want to handle: anything reaching the network usually does, and that argues for caller-controlled initialization. Finally consider the consumers you are shipping to — an application you fully control has more freedom here than a published library, where making the whole package asynchronous-only is a compatibility decision you cannot easily take back.