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

avatar

Borislav Hadzhiev

Thu Mar 24 20223 min read

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

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 {} 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)

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();

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 downleveled 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.

Use the search field on my Home Page to filter through my more than 1,000 articles.