topLevelAwaits

Reports top-level await expressions in files that export values.

✅ This rule is included in the ts logicalStrict presets.

Top-level await (“TLA”) allows using await at the module level. While convenient for standalone files run like scripts, it can cause issues if those files are imported by other modules:

• Modules using top-level await block their dependents until the await resolves
• This can cause unexpected delays in application startup
• It makes module loading order slower and sometimes less predictable

Examples

❌ Incorrect

const config = await import("./config.json");
export const apiUrl = config.apiUrl;

const data = await fetch("/api/data").then((r) => r.json());
export { data };

✅ Correct

let config: Config;

export async function getConfig() {
  if (!config) {
    config = await import("./config.json");
  }
  return config;
}

export async function fetchData() {
  return fetch("/api/data").then((r) => r.json());
}

Options

This rule is not configurable.

When Not To Use It

If you’re intentionally using top-level await for module initialization and understand the implications for module loading, you may disable this rule. You might consider using Flint disable comments and/or configuration file disables for those specific situations instead of completely disabling this rule.

Further Reading

• MDN: Top-level await
• V8: Top-level await

Equivalents in Other Linters

• ESLint: unicorn/prefer-top-level-await