Asynchronous programming is a core part of JavaScript development, especially when dealing with tasks like network requests, file operations, or any I/O-bound tasks.
But until recently, writing asynchronous code at the top level of a module wasn’t as straightforward as it could be. Developers had to wrap await in an async function, even for the simplest operations.
Enter Top-Level Await, a feature introduced in ECMAScript 2022 (ES13), which allows you to use await directly at the top level of your JavaScript modules.
This seemingly small change brings significant improvements to the language, making asynchronous code cleaner, more intuitive, and easier to reason about.
In this article, we’ll explore Top-Level Await, how it works, the problems it solves, and showcase real-world examples of how you can take advantage of this powerful feature in your projects.
What is Top-Level Await?
In previous versions of JavaScript, await could only be used inside an async function. If you wanted to use await outside of a function (such as at the top level of your module), you had to wrap it in an async function. This added unnecessary boilerplate and made your code harder to follow.
With Top-Level Await, you can now use await directly at the module’s top level, making asynchronous operations more seamless and reducing the need for additional function wrappers.
The Key Difference
Without Top-Level Await:
// This required wrapping async code in a function.
async function fetchData() {
const response = await fetch('https://api.example.com/data');
const data = await response.json();
console.log(data);
}
fetchData();
With Top-Level Await:
// No need to wrap in a function anymore.
const response = await fetch('https://api.example.com/data');
const data = await response.json();
console.log(data);
In this example, the asynchronous fetch operation is now directly accessible at the top level of the module, improving readability and simplifying the code structure.
Why Top-Level Await Matters
Cleaner, More Readable Code
One of the most significant benefits of Top-Level Await is the reduction in boilerplate code. As we saw in the example above, there’s no need to wrap asynchronous calls in an async function when using await. This not only makes your code more concise but also makes it easier to understand.
Better for Modular Code
In a module-based JavaScript environment (like when working with ES modules),
Top-Level Await helps streamline asynchronous logic at the module level. You no longer need to manage asynchronous operations inside a separate function just to await a promise.
This allows you to write asynchronous code directly where it belongs — at the top level of the module, reducing the need for excessive nesting and improving the clarity of your codebase.
Simplified Error Handling
With Top-Level Await, error handling becomes simpler. You no longer need to manage promise rejection inside an async function. Instead, you can use try…catch directly at the top level of your module to handle errors in a clean, non-nested way.
How Does Top-Level Await Work?
Asynchronous Modules
Top-Level Await only works in modules (i.e., files that are imported using the import keyword). Traditional scripts won’t support Top-Level Await, so to use this feature, you need to use ES Modules.
To ensure you’re working with an ES module, make sure your file has a .mjs extension or add “type”: “module” in your package.json.
Example of Using Top-Level Await in a Module
// app.mjs
// Awaiting a network request at the top level of the module
const response = await fetch('https://jsonplaceholder.typicode.com/todos/1');
const todo = await response.json();
console.log(todo);
Important Notes: Top-Level Await only works in ES modules.
The module’s execution is paused until the await resolves, meaning that other code in the module won’t run until the awaited promises are resolved.
Modules that use Top-Level Await must be loaded asynchronously. This means the file will be fetched and parsed as a module, not as a traditional script.
Real-World Example: Fetching API Data One of the most common use cases for Top-Level Await is fetching data from an API, such as when you’re loading data for a web page. Here’s how Top-Level Await can simplify this process.
Without Top-Level Await (Old Way)
// app.js
async function loadData() {
try {
const response = await fetch('https://jsonplaceholder.typicode.com/posts');
const posts = await response.json();
console.log(posts);
} catch (error) {
console.error('Error fetching data:', error);
}
}
loadData();
With Top-Level Await (New Way)
// app.mjs (ES module)
try {
const response = await fetch('https://jsonplaceholder.typicode.com/posts');
const posts = await response.json();
console.log(posts);
} catch (error) {
console.error('Error fetching data:', error);
}
In this updated code, you no longer need to wrap the await calls inside an async function. The code is simpler, and we directly handle the asynchronous operations.
Key Considerations When Using Top-Level Await
Error Handling
Even though Top-Level Await simplifies your code, it’s still important to manage errors effectively. Since the module is paused while awaiting the promise, a failure in one asynchronous call can block the entire module. This means you must always handle rejections using try…catch blocks.
try {
const data = await fetchDataFromApi();
console.log(data);
} catch (error) {
console.error("Failed to fetch data:", error);
}
Module Loading Order
Since the execution of your module is paused until the awaited promise resolves, ensure that you manage dependencies carefully. If your module depends on several promises, they may run in sequence, potentially introducing delays in loading other resources.
To mitigate this, consider using concurrent promises when possible.
// Concurrently fetching two resources
const [userData, postData] = await Promise.all([
fetch('https://jsonplaceholder.typicode.com/users').then(res => res.json()),
fetch('https://jsonplaceholder.typicode.com/posts').then(res => res.json())
]);
console.log(userData, postData);
When Should You Use Top-Level Await?
While Top-Level Await is a fantastic feature for simplifying asynchronous code, it’s not always appropriate for every situation. Here’s when it’s most beneficial:
Fetching Data or Resources at the Module Level
Top-Level Await works great when you need to fetch data or resources before running any logic in your module.
Simplifying Module-Scoped Asynchronous Logic
If your module is self-contained and doesn’t rely on external scripts or functions, Top-Level Await is perfect for handling asynchronous code in a natural way.
Keeping Code Clean and Readable
If you want to avoid nested async functions and make your module more concise and readable, Top-Level Await can significantly reduce complexity.
Conclusion
Top-Level Await is a powerful feature that brings JavaScript closer to a more synchronous-like experience when working with asynchronous code.
It simplifies your code, reduces boilerplate, and enhances readability, all while preserving the non-blocking nature of JavaScript.
As a full-stack developer, embracing this feature will help you write cleaner, more intuitive code when dealing with asynchronous operations.
Whether you’re fetching data, loading resources, or working with dynamic imports, Top-Level Await is an excellent tool in your JavaScript toolkit.
By keeping up with the latest JavaScript features like this, you can stay ahead of the curve, build more efficient applications, and make your code more maintainable.
