{"id":22886,"library":"vite-plugin-top-level-await","title":"Vite Plugin Top-Level Await","description":"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.","status":"active","version":"1.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/Menci/vite-plugin-top-level-await","tags":["javascript","vite","plugin","top-level await","await"],"install":[{"cmd":"npm install vite-plugin-top-level-await","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-top-level-await","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-top-level-await","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required to function as a Vite plugin","package":"vite","optional":false}],"imports":[{"note":"This package is ESM-only and cannot be used with require(). Use default import.","wrong":"const topLevelAwait = require('vite-plugin-top-level-await')","symbol":"topLevelAwait","correct":"import topLevelAwait from 'vite-plugin-top-level-await'"},{"note":"Type import for TypeScript users to type the plugin options object.","wrong":"","symbol":"VitePluginTopLevelAwaitOptions","correct":"import type { VitePluginTopLevelAwaitOptions } from 'vite-plugin-top-level-await'"},{"note":"The return type of topLevelAwait() is Vite's Plugin type. Import from Vite, not this package.","wrong":"","symbol":"Plugin","correct":"import { Plugin } from 'vite'"}],"quickstart":{"code":"// vite.config.js\nimport { defineConfig } from 'vite';\nimport topLevelAwait from 'vite-plugin-top-level-await';\n\nexport default defineConfig({\n  plugins: [\n    topLevelAwait({\n      promiseExportName: '__tla',\n      promiseImportName: i => `__tla_${i}`\n    })\n  ]\n});\n\n// src/main.js - uses top-level await\nimport { fetchData } from './data.js';\nconst data = await fetchData();\nexport { data };","lang":"javascript","description":"Basic Vite config using plugin with default options, plus example of top-level await usage in source code."},"warnings":[{"fix":"Place vite-plugin-top-level-await early in the plugins array, after transformations that modify bundle structure.","message":"Plugin may fail if other plugins transform the bundle before it, as it relies on parsing Rollup's output export statement.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure no circular dependencies with top-level await, or design code to handle missing exports.","message":"When an TLA dependency is being awaited, accessing its exports will NOT raise an exception (circular dependency handling may be unexpected).","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"For Firefox support, use IIFE format and follow the documented pattern for worker instantiation.","message":"Worker IIFE mode requires building worker as ES first then converting, which adds complexity.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change to import statement: import topLevelAwait from 'vite-plugin-top-level-await'","cause":"Using require() to import the plugin,","error":"Error: The plugin 'vite:top-level-await' doesn't support CommonJS. Use 'import' instead of 'require'."},{"fix":"Use default import: import topLevelAwait from 'vite-plugin-top-level-await' (no destructuring)","cause":"Accidentally imported a named export instead of default,","error":"TypeError: topLevelAwait is not a function"},{"fix":"Install vite: npm install -D vite","cause":"Missing Vite peer dependency,","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'vite'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}