Skip to main content

Demo 36

Top-level await blocks importers

A module with top-level await pauses evaluation of modules that import it.

fully simulatedcurated scenariodoes not execute real code
Short answer

The key output order is load config -> config ready. Top-level await makes module loading asynchronous for everything that depends on it.

Real-world bug this helps solve

A Node callback, timer, I/O task, stream, or worker-pool job runs later than expected. This affects Next.js tooling, Node CLIs, config loaders, migrations, server startup, and test environments.

Common wrong assumption

Putting slow startup work in a widely imported module without noticing app boot delay.

Fix direction

Separate sync work, microtasks, timers, I/O, check callbacks, and worker-pool work in your mental model.

Fixed code pattern
setImmediate(runAfterIO);
// Avoid long nextTick loops that starve other phases.
Visual proof

The console lane proves the visible order: load config -> config ready. The active line and queues show why source order changed.

How to verify in a real app

Add timestamps around callbacks and inspect Node diagnostics, logs, or profiler output to confirm the runtime phase that is delaying work.

Share
Loading visual timeline...

Related cases

Continue with nearby confusion while the mental model is fresh.

Recommended next

Was this clear?

This stays local for now. It helps you track where the product still needs sharper cases.

Send detail