rollup-plugin-workers

2.1.1 verified Mon Apr 27 auth: no javascript

A Rollup plugin that adds code splitting for JavaScript module Workers (Web Workers, Shared Workers, Service Workers) and Worklets (AudioWorklet, PaintWorklet, LayoutWorklet, AnimationWorklet). Current stable version: 2.1.1. Works with Rollup >= 1.11.0. It transforms Worker/Worklet import patterns into separate output chunks, enabling dynamic code splitting for multithreaded applications. Unlike generic worker plugins, this plugin specifically targets module-type workers and supports ES module format in workers. Does not include a module loader; users must handle chunk loading.

Common errors

error Error: Cannot find module 'rollup-plugin-workers' ↓

cause Package not installed or CommonJS require used in ESM context.

fix

Install the package: npm install -D rollup-plugin-workers. Use import syntax instead of require.

error TypeError: worker is not a function ↓

cause Named import used instead of default import.

fix

Change import to default import: import worker from 'rollup-plugin-workers'.

error Error: The Rollup version is not supported by rollup-plugin-workers ↓

cause Rollup version is below 1.11.0.

fix

Upgrade Rollup to version >= 1.11.0.

Warnings

breaking Requires Rollup >= 1.11.0; older versions will fail to load the plugin. ↓

fix Upgrade Rollup to version 1.11.0 or higher.

gotcha Plugin does not include a module loader. You must handle loading of split chunks manually in the browser. ↓

fix Provide a module loader or use a bundler that supports automatic chunk loading (e.g., Vite).

gotcha Worklet calls must exactly follow format '*.*Worklet.addModule(...)'. Arbitrary function calls won't be recognized. ↓

fix Ensure worklet registration uses the pattern obj.worklet.addModule, where worklet is one of: AudioWorklet, PaintWorklet, LayoutWorklet, AnimationWorklet.

gotcha Workers must be of type 'module' and use the correct constructor signature (e.g., new Worker('./worker.js', { type: 'module' })). ↓

fix Always pass { type: 'module' } as second argument to Worker/SharedWorker constructors, and for ServiceWorker use { type: 'module' } in register().

Install

npm install rollup-plugin-workers

yarn add rollup-plugin-workers

pnpm add rollup-plugin-workers

Imports

default

wrong

const worker = require('rollup-plugin-workers')

correct

import worker from 'rollup-plugin-workers'

Plugin is ESM-only; CommonJS require will fail unless using dynamic import.

worker
```
import { default as worker } from 'rollup-plugin-workers'
```
Default export only; named export 'worker' is not available.

Rollup plugin usage

wrong

import { worker } from 'rollup-plugin-workers'

correct

import worker from 'rollup-plugin-workers';

export default {
  plugins: [worker()]
}

The function is the default export; using named import will result in undefined.

Quickstart

Demonstrates basic Rollup configuration with the workers plugin to enable code splitting for module workers.

import worker from 'rollup-plugin-workers';

export default {
  input: 'main.js',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [worker()]
};