Registry / web-framework / vite-plugin-top-level-await

vite-plugin-top-level-await

library1.6.0jsnpmunverified

A Vite plugin that transforms ES modules using top-level await (TLA) into compatible code for browsers that do not natively support TLA. Version 1.6.0 is current, with a moderate release cadence. It works by rewriting imports and exports to use Promise-based orchestration, handling circular dependencies correctly. Unlike setting build.target to esnext, this plugin retains compatibility with Vite's default browser targets. Supports both ES and IIFE worker formats. Notable alternatives include vite-plugin-top-level-await by Menci (this one) and manualPromise-based polyfilling; this plugin is the most popular and actively maintained for Vite ≥2.8.

web-framework devops

npm install vite-plugin-top-level-await

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-TOP-LE

vite-plugin-top-level-await

web-frameworkjavascriptv1.6.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

topLevelAwait

✓ import topLevelAwait from 'vite-plugin-top-level-await'

✗ const topLevelAwait = require('vite-plugin-top-level-await')

This package is ESM-only and cannot be used with require(). Use default import.

VitePluginTopLevelAwaitOptions

✓ import type { VitePluginTopLevelAwaitOptions } from 'vite-plugin-top-level-await'

Type import for TypeScript users to type the plugin options object.

Plugin

✓ import { Plugin } from 'vite'

The return type of topLevelAwait() is Vite's Plugin type. Import from Vite, not this package.

Basic Vite config using plugin with default options, plus example of top-level await usage in source code.

// vite.config.js import { defineConfig } from 'vite'; import topLevelAwait from 'vite-plugin-top-level-await'; export default defineConfig({ plugins: [ topLevelAwait({ promiseExportName: '__tla', promiseImportName: i => `__tla_${i}` }) ] }); // src/main.js - uses top-level await import { fetchData } from './data.js'; const data = await fetchData(); export { data };

Debug

Known issues

gotchaPlugin may fail if other plugins transform the bundle before it, as it relies on parsing Rollup's output export statement.

fix

Place vite-plugin-top-level-await early in the plugins array, after transformations that modify bundle structure.

affects: >=0.0.0

gotchaWhen an TLA dependency is being awaited, accessing its exports will NOT raise an exception (circular dependency handling may be unexpected).

fix

Ensure no circular dependencies with top-level await, or design code to handle missing exports.

affects: >=0.0.0

gotchaWorker IIFE mode requires building worker as ES first then converting, which adds complexity.

fix

For Firefox support, use IIFE format and follow the documented pattern for worker instantiation.

affects: >=0.0.0

Errors

Common errors & fixes

Error: The plugin 'vite:top-level-await' doesn't support CommonJS. Use 'import' instead of 'require'.

Using require() to import the plugin,

fix

Change to import statement: import topLevelAwait from 'vite-plugin-top-level-await'

TypeError: topLevelAwait is not a function

Accidentally imported a named export instead of default,

fix

Use default import: import topLevelAwait from 'vite-plugin-top-level-await' (no destructuring)

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'vite'

Missing Vite peer dependency,

fix

Install vite: npm install -D vite

Upgrade

Version history

1.6.0latest on npm

Audit

Dependencies

viterequiredPeer dependency required to function as a Vite plugin

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Menci/vite-plugin-top-level-await ↗

packagehttps://www.npmjs.com/package/vite-plugin-top-level-await ↗