{"id":16197651,"url":"https://github.com/menci/vite-plugin-top-level-await","last_synced_at":"2025-05-14T20:09:10.511Z","repository":{"id":41277230,"uuid":"464408338","full_name":"Menci/vite-plugin-top-level-await","owner":"Menci","description":"Transform code to support top-level await in normal browsers for Vite.","archived":false,"fork":false,"pushed_at":"2025-02-14T15:37:56.000Z","size":363,"stargazers_count":298,"open_issues_count":14,"forks_count":18,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-11T00:01:55.932Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Menci.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-02-28T09:02:14.000Z","updated_at":"2025-04-27T21:25:26.000Z","dependencies_parsed_at":"2023-02-19T10:00:20.769Z","dependency_job_id":"e03f21f1-f50f-43ae-a45c-70246e7535dd","html_url":"https://github.com/Menci/vite-plugin-top-level-await","commit_stats":{"total_commits":41,"total_committers":3,"mean_commits":"13.666666666666666","dds":0.04878048780487809,"last_synced_commit":"751da5e9cc7e36287fb16b97dde485c650acf233"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Menci%2Fvite-plugin-top-level-await","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Menci%2Fvite-plugin-top-level-await/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Menci%2Fvite-plugin-top-level-await/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Menci%2Fvite-plugin-top-level-await/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Menci","download_url":"https://codeload.github.com/Menci/vite-plugin-top-level-await/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254219374,"owners_count":22034397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T09:08:21.811Z","updated_at":"2025-05-14T20:09:10.493Z","avatar_url":"https://github.com/Menci.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vite-plugin-top-level-await\n\n[![Test Status](https://img.shields.io/github/actions/workflow/status/Menci/vite-plugin-top-level-await/test.yaml?branch=main\u0026style=flat-square)](https://github.com/Menci/vite-plugin-top-level-await/actions?query=workflow%3ATest)\n[![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)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square)](http://commitizen.github.io/cz-cli/)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)\n[![License](https://img.shields.io/github/license/Menci/vite-plugin-top-level-await?style=flat-square)](LICENSE)\n\nTransform 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`.\n\n## Installation\n\n```bash\nyarn add -D vite-plugin-top-level-await\n```\n\n## Usage\n\nPut 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.\n\n```typescript\nimport topLevelAwait from \"vite-plugin-top-level-await\";\n\nexport default defineConfig({\n  plugins: [\n    topLevelAwait({\n      // The export name of top-level await promise for each chunk module\n      promiseExportName: \"__tla\",\n      // The function to generate import names of top-level await promise in each chunk module\n      promiseImportName: i =\u003e `__tla_${i}`\n    })\n  ]\n});\n```\n\n## Workers\n\nYou can use this plugin for workers (by putting it in `config.worker.plugins`).\n\n* If the worker format is ES, the plugin works normally.\n* 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.\n  ```js\n  const myWorker = import.meta.env.DEV\n      // In development mode, `import`s in workers are not transformed, so you\n      // must use `{ type: \"module\" }`.\n    ? new Worker(new URL(\"./my-worker.js\", import.meta.url), { type: \"module\" })\n      // In build mode, let Vite and vite-plugin-top-level-await build a single-file\n      // bundle of your worker that works on both modern browsers and Firefox.\n    : new Worker(new URL(\"./my-worker.js\", import.meta.url), { type: \"classic\" });\n  ```\n\n## Note\n\nThis plugin transforms code from:\n\n```js\nimport { a } from \"./a.js\"; // This module uses top-level await\nimport { b } from \"./b.js\"; // This module uses top-level await too\nimport { c } from \"./c.js\"; // This module does NOT use top-level await\n\nconst x = 1;\nawait b.func();\nconst { y } = await somePromise;\n\nexport { x, y };\n```\n\nTo:\n\n```js\nimport { a, __tla as __tla_0 } from \"./a.js\"; // This module uses top-level await\nimport { b, __tla as __tla_1 } from \"./b.js\"; // This module uses top-level await too\nimport { c } from \"./c.js\"; // This module does NOT use top-level await\n\n// Original exported variables\nlet x, y;\n\n// Await imported TLA promises and execute original top-level statements\nlet __tla = Promise.all([\n  (() =\u003e { try { return __tla_0; } catch {} })(),\n  (() =\u003e { try { return __tla_1; } catch {} })()\n]).then(async () =\u003e {\n  // Transform exported variables to assignments\n  x = 1;\n\n  await b.func();\n\n  // Destructing patterns (and function / class declarations as well) are handled correctly\n  ({ y } = await somePromise);\n});\n\n// Export top-level await promise\nexport { x, y, __tla };\n```\n\nIt 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmenci%2Fvite-plugin-top-level-await","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmenci%2Fvite-plugin-top-level-await","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmenci%2Fvite-plugin-top-level-await/lists"}