Last updated: Jan 24, 2023
Reading time·3 min
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.
Here is an example of how the error occurs.
// ⛔️ 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.
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)
await
keyword inside of an async
functionOne way to solve the error is to use the await
keyword inside of an async
function.
async function example() { const result = await Promise.resolve(42); console.log(result); // 👉️ 42 // 👉️ result is available here } example();
tsconfig.json
to support top-level awaitAlternatively, 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.
{ "compilerOptions": { "target": "es2017", "module": "es2022", }, "include": ["src/**/*"], "exclude": ["node_modules"] }
Now I am able to use top-level await
in my index.ts
file.
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.
{ "type": "module", // ... rest }
Now you can run your file that contains top-level await.
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.
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.
You can learn more about the related topics by checking out the following tutorials: