Top-level await expressions are only allowed when the module option is set to es2022

avatar
Borislav Hadzhiev

Last updated: Jan 24, 2023
3 min

banner

# Top-level await expressions are only allowed when the module option is set to es2022

To solve the error "Top-level 'await' expressions are only allowed when the 'module' option is set to 'es2022', 'esnext'", use the await keyword in an async function or set the module option to es2022 and target to es2017 in your tsconfig.json file.

top level await expressions are only allowed

Here is an example of how the error occurs.

index.ts
// ⛔️ Error: Top-level 'await' expressions are only allowed // when the 'module' option is set to 'es2022', 'esnext', // 'system', or 'nodenext', and the 'target' option is set to 'es2017' or higher.ts(1378) const result = await Promise.resolve(42); console.log(result); export {};

I used the export {} line to make the file an ES module because await expressions are only allowed at the top level of a file that is a module, otherwise, an error is issued.

index.ts
const result = await Promise.resolve(42); console.log(result); // ⛔️ Error: 'await' expressions are only allowed at the top level // of a file when that file is a module, but this file has no imports // or exports. Consider adding an empty 'export {}' to make this file a module.ts(1375)

# Using the await keyword inside of an async function

One way to solve the error is to use the await keyword inside of an async function.

index.ts
async function example() { const result = await Promise.resolve(42); console.log(result); // 👉️ 42 // 👉️ result is available here } example();

using await keyword inside async function

# Updating your tsconfig.json to support top-level await

Alternatively, you can update your tsconfig.json file to support top-level await in your project.

To enable top-level await in your TypeScript project, open your tsconfig.json file and set:

  • module to es2022 (or higher)
  • target to es2017 (or higher) or ESNext

Note that you may also have to set the option in your tsconfig.app.json file if using Angular, or whichever config file is used in your build process.

tsconfig.json
{ "compilerOptions": { "target": "es2017", "module": "es2022", }, "include": ["src/**/*"], "exclude": ["node_modules"] }
Restart your IDE and development server after making the changes.

Now I am able to use top-level await in my index.ts file.

index.ts
const result = await Promise.resolve(42); console.log(result); export {};

If you get an error "To load an ES module, set "type": "module" in the package.json or use the .mjs extension.", you also have to set type to module in your package.json file.

package.json
{ "type": "module", // ... rest }

Now you can run your file that contains top-level await.

shell
tsc && node build/index.js

If you use the include or files options, make sure the file you are using top-level await in is included in your project and is being tracked by TypeScript.

The module option sets the module system for the project.

The difference between having module set to es6 and es2022 (or esnext) is that es2022 adds support for top-level await.

The target option changes which JavaScript features are down-leveled and which are left intact.

For example, arrow functions get converted to regular functions if your target is ES5 or lower.

When you set your target option to es2017, you are essentially saying that you don't want to support browsers that don't support es2017 features.

Depending on your environment, this might not matter. For example, if you only target modern browsers or are writing server-side code, you'll probably be just fine.

Just make sure the emitted JavaScript is able to run in the environments where you intend to run your application.

# Additional Resources

You can learn more about the related topics by checking out the following tutorials:

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.
book cover
You can use the search field on my Home Page to filter through all of my articles.