rollup-plugin-concurrent-top-level-await

0.4.1 verified Mon Apr 27 auth: no javascript

Rollup and Vite plugin (v0.4.1) that restores concurrent execution of modules with top-level await (TLA), which Rollup/Vite otherwise serialize. Provides near-perfect evaluation order matching V8 (99%+ on tla-fuzzer) by transforming both TLA-containing modules and their ancestor modules up to the lowest common ancestor. Ships TypeScript types, supports include/exclude filters, source maps, and configurable variable prefix. Requires Rollup ^4.0.0 or Vite >=5.0.0 <8.0.0. Not compatible with Rolldown or Vite >=8. Does not polyfill TLA—runtime support needed.

Common errors

error Error: Cannot find module 'rollup-plugin-concurrent-top-level-await' ↓

cause Package not installed or not in node_modules.

fix

Run npm install --save-dev rollup-plugin-concurrent-top-level-await

error TypeError: concurrentTopLevelAwait is not a function ↓

cause Using named import `{ concurrentTopLevelAwait }` instead of default import.

fix

Change to import concurrentTopLevelAwait from 'rollup-plugin-concurrent-top-level-await'

error Error: This plugin is not compatible with version 8.x of Vite. Check peer dependencies. ↓

cause Vite version >=8.0.0 is not supported (plugin requires <8.0.0).

fix

Downgrade Vite to 7.x or use rolldown-plugin-concurrent-top-level-await instead.

error Error: (plugin concurrent-top-level-await) Could not resolve source map ↓

cause Source map generation failed for a transformed file, often due to incorrect include/exclude patterns.

fix

Ensure include covers all ancestor modules and that source maps are enabled (sourceMap: true).

Warnings

breaking Plugin is incompatible with Rolldown and Vite >= 8.0.0 due to use of Rollup-specific APIs. ↓

fix Use rolldown-plugin-concurrent-top-level-await for Rolldown; stay on Vite <8.0.0 or wait for updated version.

gotcha Ancestor modules of TLA modules must also be included in the plugin's transform scope, or evaluation order may differ. ↓

fix Use include patterns that cover all modules on the import path from entry to TLA modules (see README section).

gotcha The plugin does not polyfill top-level await; runtime support (e.g., modern browser, Node 22+) is required. ↓

fix If targeting older environments, use vite-plugin-top-level-await to polyfill TLA.

deprecated The `experimental.nativeMagicString` option in Rolldown is no longer required but also not used here; may confuse users migrating. ↓

fix No action needed; this option is ignored by the plugin.

Install

npm install rollup-plugin-concurrent-top-level-await

yarn add rollup-plugin-concurrent-top-level-await

pnpm add rollup-plugin-concurrent-top-level-await

Imports

default

wrong

const { concurrentTopLevelAwait } = require('rollup-plugin-concurrent-top-level-await')

correct

import concurrentTopLevelAwait from 'rollup-plugin-concurrent-top-level-await'

Default export is a function; named export does not exist. CJS require() returns the default export as module.exports.

default (CJS)

wrong

const { default: concurrentTopLevelAwait } = require('rollup-plugin-concurrent-top-level-await')

correct

const concurrentTopLevelAwait = require('rollup-plugin-concurrent-top-level-await')

In CommonJS, the plugin is the default export directly; no .default needed.

Plugin type (TypeScript only)
wrong
```
import { Plugin } from 'rollup-plugin-concurrent-top-level-await'
```
correct
```
import type { Plugin } from 'rollup'
```
The package does not export a Plugin type; use Rollup's or Vite's own type.

Options type

import type { ConcurrentTopLevelAwaitOptions } from 'rollup-plugin-concurrent-top-level-await'

Available from v0.4.0+. Not needed for JavaScript users.

Quickstart

Basic Rollup config using the plugin with include/exclude filters, source maps, and custom variable prefix.

// rollup.config.js
import concurrentTopLevelAwait from 'rollup-plugin-concurrent-top-level-await';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [
    concurrentTopLevelAwait({
      include: '**/*.js',
      exclude: 'node_modules/**',
      sourceMap: true,
      generatedVariablePrefix: '__tla'
    })
  ]
};

// Install: npm install --save-dev rollup rollup-plugin-concurrent-top-level-await