# vite-plugin-top-level-await

> Transform code to support top-level await in normal browsers for Vite.

Latest version **1.6.0** (published 2025-07-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install vite-plugin-top-level-await
pnpm add vite-plugin-top-level-await
yarn add vite-plugin-top-level-await
bun add vite-plugin-top-level-await
```

## Health

**Score 40/100 (D)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.6.0 |
| Published | 2025-07-17 |
| First published | 2022-03-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 49.8 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 312 |
| Author | Menci |
| Maintainers | menci |
| Keywords | vite, plugin, top-level await, await |

## Links

- npm: https://www.npmjs.com/package/vite-plugin-top-level-await
- Repository: https://github.com/Menci/vite-plugin-top-level-await
- Homepage: https://github.com/Menci/vite-plugin-top-level-await#readme
- Issues: https://github.com/Menci/vite-plugin-top-level-await/issues
- npm.io page: https://npm.io/package/vite-plugin-top-level-await

## Dependencies (4)

- [uuid](https://npm.io/package/uuid.md) 10.0.0
- [@swc/core](https://npm.io/package/@swc/core.md) ^1.12.14
- [@swc/wasm](https://npm.io/package/@swc/wasm.md) ^1.12.14
- [@rollup/plugin-virtual](https://npm.io/package/@rollup/plugin-virtual.md) ^3.0.2

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 1.6.0 (latest) — 2025-07-17
- 1.5.0 — 2025-02-14
- 1.4.4 — 2024-08-09
- 1.4.3 — 2024-08-08
- 1.4.2 — 2024-07-19
- 1.4.1 — 2023-12-13
- 1.4.0 — 2023-12-10
- 1.3.1 — 2023-05-20
- 1.3.0 — 2023-02-25
- 1.2.4 — 2023-02-06
- 1.2.3 — 2023-01-27
- 1.2.2 — 2022-11-23
- 1.2.1 — 2022-10-22
- 1.2.0 — 2022-10-21
- 1.1.1 — 2022-07-20
- … 7 more at https://npm.io/package/vite-plugin-top-level-await/versions

## README

# vite-plugin-top-level-await

[![Test Status](https://img.shields.io/github/actions/workflow/status/Menci/vite-plugin-top-level-await/test.yaml?branch=main&style=flat-square)](https://github.com/Menci/vite-plugin-top-level-await/actions?query=workflow%3ATest)
[![npm](https://img.shields.io/npm/v/vite-plugin-top-level-await?style=flat-square)](https://www.npmjs.com/package/vite-plugin-top-level-await)
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square)](http://commitizen.github.io/cz-cli/)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
[![License](https://img.shields.io/github/license/Menci/vite-plugin-top-level-await?style=flat-square)](LICENSE)

Transform code to support top-level await in normal browsers for Vite. Support all modern browsers of Vite's default target without need to set `build.target` to `esnext`.

## Installation

```bash
yarn add -D vite-plugin-top-level-await
```

## Usage

Put this plugin in your plugin list. At most case you don't need to care the order, but if there're any plugin transforming bundle before it, there's a little chance that this plugin fails to parse code since it does only parse Rollup's output `export { ... }` export statement.

```typescript
import topLevelAwait from "vite-plugin-top-level-await";

export default defineConfig({
  plugins: [
    topLevelAwait({
      // The export name of top-level await promise for each chunk module
      promiseExportName: "__tla",
      // The function to generate import names of top-level await promise in each chunk module
      promiseImportName: i => `__tla_${i}`
    })
  ]
});
```

## Workers

You can use this plugin for workers (by putting it in `config.worker.plugins`).

* If the worker format is ES, the plugin works normally.
* If the worker format is IIFE, the plugin first let Vite build your worker as an ES bundle since IIFE doesn't support top-level awaits, and then build the transformed ES bundle to IIFE. Please use IIFE when targeting Firefox.
  ```js
  const myWorker = import.meta.env.DEV
      // In development mode, `import`s in workers are not transformed, so you
      // must use `{ type: "module" }`.
    ? new Worker(new URL("./my-worker.js", import.meta.url), { type: "module" })
      // In build mode, let Vite and vite-plugin-top-level-await build a single-file
      // bundle of your worker that works on both modern browsers and Firefox.
    : new Worker(new URL("./my-worker.js", import.meta.url), { type: "classic" });
  ```

## Note

This plugin transforms code from:

```js
import { a } from "./a.js"; // This module uses top-level await
import { b } from "./b.js"; // This module uses top-level await too
import { c } from "./c.js"; // This module does NOT use top-level await

const x = 1;
await b.func();
const { y } = await somePromise;

export { x, y };
```

To:

```js
import { a, __tla as __tla_0 } from "./a.js"; // This module uses top-level await
import { b, __tla as __tla_1 } from "./b.js"; // This module uses top-level await too
import { c } from "./c.js"; // This module does NOT use top-level await

// Original exported variables
let x, y;

// Await imported TLA promises and execute original top-level statements
let __tla = Promise.all([
  (() => { try { return __tla_0; } catch {} })(),
  (() => { try { return __tla_1; } catch {} })()
]).then(async () => {
  // Transform exported variables to assignments
  x = 1;

  await b.func();

  // Destructing patterns (and function / class declarations as well) are handled correctly
  ({ y } = await somePromise);
});

// Export top-level await promise
export { x, y, __tla };
```

It could handle **correct usage** of circular dependencies with the default behavior of ES standard. But when an TLA dependency is being awaited, an accessing to one of its exports **will NOT raise an exception**. At most time you don't need to care about this. These *could* be supported by doing more transformations of the whole AST but it will make building a lot slower. Open an issue and tell me your scenario if you really need the exception.

---
_Source: https://npm.io/package/vite-plugin-top-level-await · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._