rollup-plugin-web-worker-loader

1.7.0 verified Mon Apr 27 auth: no javascript

Rollup plugin for bundling Web Workers, Service Workers, Shared Workers, Audio Worklets, and Paint Worklets. Current stable version is 1.7.0; published regularly. Supports inlining worker code or emitting separate script files via code-splitting. Handles worker dependencies, source maps, and Node.js environments. Differentiators include support for multiple worker/worklet types, Node.js compatibility, and automatic platform detection. Requires Rollup 1.9+ up to 4.x.

Common errors

error SyntaxError: Named export 'default' not found. The requested module 'rollup-plugin-web-worker-loader' is a CommonJS module, which may not support all module.exports as named exports. ↓

cause The plugin is an ESM-only default export; CommonJS require() or named import destructuring fails.

fix

Use import webWorkerLoader from 'rollup-plugin-web-worker-loader' (ESM) or if using CJS, use const webWorkerLoader = require('rollup-plugin-web-worker-loader').default.

error Error: The 'web-worker' prefix is not configured. Use the 'webWorkerLoader' plugin options to set a custom pattern. ↓

cause The import specifier uses a custom prefix not defined in the plugin config.

fix

Either use the default 'web-worker:' prefix, or configure a custom RegEx in the plugin options under the 'web-worker' key.

Warnings

gotcha The plugin can only be used with Rollup's module format (ESM or CJS). It does not support UMD or IIFE output formats. ↓

fix Set output.format to 'esm' or 'cjs'.

deprecated Using 'web-worker:' prefix without specifying a targetPlatform may produce inline code in some cases; the 'auto' mode attempts to detect the environment but can misbehave in mixed contexts. ↓

fix Explicitly set targetPlatform to 'browser' or 'node'.

breaking Version 1.0.0 changed the import pattern from a query string (?worker) to a prefix scheme (web-worker:). Old imports using ?worker will fail. ↓

fix Replace import MyWorker from './MyWorker?worker' with import MyWorker from 'web-worker:./MyWorker'.

Install

npm install rollup-plugin-web-worker-loader

yarn add rollup-plugin-web-worker-loader

pnpm add rollup-plugin-web-worker-loader

Imports

default (plugin function)

wrong

const webWorkerLoader = require('rollup-plugin-web-worker-loader');

correct

import webWorkerLoader from 'rollup-plugin-web-worker-loader';

ESM default export; CJS require() works with some bundlers but not recommended.

Web Worker import
wrong
```
import DataWorker from 'rollup-plugin-web-worker-loader!./DataWorker';
```
correct
```
import DataWorker from 'web-worker:./DataWorker';
```
The plugin uses a prefix scheme (default: 'web-worker:') in the import specifier; no query syntax.

Service Worker import

wrong

const ServiceWorker = require('service-worker:./ServiceWorker');

correct

import ServiceWorker from 'service-worker:./ServiceWorker';

ESM-only import; ServiceWorker returns a Promise<ServiceWorkerRegistration>.

Quickstart

Minimal Rollup config with the plugin and a Web Worker import example.

import webWorkerLoader from 'rollup-plugin-web-worker-loader';
import { defineConfig } from 'rollup';

export default defineConfig({
  input: 'src/index.js',
  plugins: [
    webWorkerLoader({
      targetPlatform: 'auto',
      preserveSource: false,
      external: []
    })
  ],
  output: {
    dir: 'dist',
    format: 'esm'
  }
});

// src/index.js
import MyWorker from 'web-worker:./MyWorker';
const worker = new MyWorker();
worker.postMessage('hello');

// src/MyWorker.js
self.onmessage = (e) => {
  postMessage('received: ' + e.data);
};