Top-Level Await: Simplifying Async Module Loading

While I was looking over some legacy codebases the other day, I noticed a pattern that used to drive me absolutely crazy—wrapping entire module contents in an immediately invoked async function just to use await. I was once guilty of writing this awkward boilerplate myself, but little did I know that ES2022 would finally rescue us from this mess.

The Problem with Async Module Initialization

Before top-level await became available, initializing modules with asynchronous operations felt clunky. You'd have to choose between several bad options: using promises without await (making your code harder to read), wrapping everything in an IIFE, or exporting a promise that consumers would need to handle. None of these felt natural.

I remember working on a project where we needed to load configuration from a remote API before the module could export its functionality. The code looked terrible, and every new developer who joined the team asked why we couldn't just use await directly. When I finally decided to investigate top-level await, I realized it solved this exact problem.

What Is Top-Level Await and How Does It Work?

Top-level await allows you to use the await keyword at the top level of ES modules without wrapping it in an async function. This feature transforms how we handle asynchronous module initialization by making the module itself behave like an async function.

The key thing to understand is that when a module uses top-level await, it essentially becomes an async boundary. Any module that imports it will wait for all top-level awaits to resolve before continuing execution. This creates a natural dependency chain that's much easier to reason about than callback-based initialization patterns.

In other words, your module's exports aren't available until all async operations complete. This might sound limiting at first, but it's actually a powerful guarantee that prevents race conditions and initialization bugs.

Before and After: IIFE Pattern vs Top-Level Await

Let me show you the difference with a real example. Here's how I used to load database configuration in the old days:

// config.js - The old way (PAINFUL!)
let dbConfig = null;
 
(async () => {
  try {
    const response = await fetch('/api/config');
    dbConfig = await response.json();
  } catch (error) {
    console.error('Failed to load config:', error);
    dbConfig = { host: 'localhost', port: 5432 }; // fallback
  }
})();
 
export { dbConfig };

The problem with this approach? When another module imports dbConfig, there's no guarantee the async function has finished executing. You'd get null values and race conditions that were nightmares to debug. I cannot stress this enough—this pattern caused more production bugs than I care to admit!

Here's the same code with top-level await:

// config.ts - The modern way (WONDERFUL!)
let dbConfig;
 
try {
  const response = await fetch('/api/config');
  dbConfig = await response.json();
} catch (error) {
  console.error('Failed to load config:', error);
  dbConfig = { host: 'localhost', port: 5432 };
}
 
export { dbConfig };

Now when you import this module, JavaScript guarantees that dbConfig is fully initialized. No race conditions, no null checks, no headaches. The importing module simply waits until this module is ready.

Practical Use Cases: Config Loading, Dynamic Imports, and Dependency Injection

I've found three scenarios where top-level await really shines. First, loading configuration files or environment-specific settings. Second, conditionally importing modules based on runtime conditions. Third, establishing database connections or other async resources before exporting functionality.

Luckily we can handle all of these elegantly now. For example, when I was building a feature flag system, I needed to fetch flags from a remote service before initializing any feature modules. With top-level await, this became trivial:

// featureFlags.ts
const flags = await fetch('https://api.example.com/flags')
  .then(res => res.json())
  .catch(() => ({ useNewDashboard: false }));
 
export const useNewDashboard = flags.useNewDashboard;

Dynamic imports based on environment are another fascinating use case. You might want to load different implementations in development versus production:

// logger.ts
const loggerModule = process.env.NODE_ENV === 'production'
  ? await import('./productionLogger.js')
  : await import('./devLogger.js');
 
export const logger = loggerModule.default;

The Critical Trade-offs: Module Blocking and Execution Order

Now here's where things get interesting—and where you need to be careful. Top-level await blocks the entire module graph. If module A imports module B, and module B uses top-level await, module A can't execute until B's awaits resolve.

This is by design, but it can create performance bottlenecks if you're not thoughtful. I came across a situation where a deeply nested module was making a slow API call, and it blocked the entire application startup for three seconds. Not ideal!

The execution order follows these rules:

• Modules are evaluated in dependency order
• Each module waits for its dependencies' top-level awaits to complete
• Multiple top-level awaits in the same module run sequentially
• Parallel module branches can load simultaneously

Understanding this helps you architect your module structure intelligently. Keep slow operations at the edges of your dependency graph when possible.

Real-World Implementation: Building an Async Configuration Loader

Let me show you a practical example I built recently—an async configuration loader that handles multiple sources with fallbacks:

// configLoader.ts
interface AppConfig {
  apiUrl: string;
  timeout: number;
  features: Record<string, boolean>;
}
 
// Try remote config first
let config: AppConfig;
 
try {
  const response = await fetch('/api/app-config', {
    signal: AbortSignal.timeout(2000) // 2 second timeout
  });
  
  if (!response.ok) {
    throw new Error(`Config fetch failed: ${response.status}`);
  }
  
  config = await response.json();
  console.log('Loaded remote configuration');
} catch (error) {
  console.warn('Remote config unavailable, using local defaults');
  
  // Fallback to local config file
  config = {
    apiUrl: 'http://localhost:3000',
    timeout: 5000,
    features: {
      darkMode: true,
      analytics: false
    }
  };
}
 
// Validate critical fields
if (!config.apiUrl || !config.timeout) {
  throw new Error('Invalid configuration: missing required fields');
}
 
// Export a frozen config object to prevent accidental mutations
export default Object.freeze(config);

This pattern has several advantages. First, it ensures configuration is loaded before any other module can use it. Second, it handles errors gracefully with fallbacks. Third, by freezing the config object, we prevent accidental mutations that could cause bugs.

When I finally decided to refactor our app to use this pattern, our initialization bugs dropped significantly. No more race conditions, no more partial state, just clean, predictable startup.

Best Practices and Anti-Patterns to Avoid

After using top-level await in production for over a year, I've learned some valuable lessons. Here are the key patterns I follow:

Do this:

• Keep top-level awaits fast (under 1 second when possible)
• Use timeouts on network requests to prevent hanging
• Provide sensible fallbacks for failed async operations
• Document that your module has async initialization
• Use top-level await for truly necessary initialization only

Avoid these mistakes:

• Don't use top-level await in modules that are imported everywhere (you'll block everything)
• Never use it for optional features that could be lazy-loaded
• Don't chain multiple slow operations sequentially—parallelize when possible
• Avoid it in library code unless absolutely necessary
• Don't forget error handling—unhandled rejections will crash the module

I was once guilty of using top-level await to fetch user preferences in a utility module that was imported by dozens of other modules. It added 200ms to every page load! Moving that to a lazy-loaded context module solved the problem immediately.

When to Use (and Not Use) Top-Level Await

Top-level await is wonderful for specific scenarios but isn't a universal solution. Use it when you need guaranteed initialization before module execution, like loading critical configuration, establishing database connections, or resolving feature flags.

Don't use it for operations that can be deferred, optional features, or anything user-initiated. If the async operation is triggered by user interaction, handle it in a regular async function instead.

The sweet spot I've found is using top-level await in configuration and initialization modules that sit at the edges of your dependency graph. This gives you clean initialization without blocking your entire application.

And that concludes the end of this post! I hope you found this valuable and look out for more in the future!