rollup-plugin-worker64

A modern Rollup plugin that automatically bundles Web Workers, Service Workers, Shared Workers, Audio Worklets, and Paint Worklets as self-contained base64 data URLs with lazy loading support.

Features

• 🚀 Zero Configuration: Automatically detects new Worker(new URL(...)) patterns
• 🎭 Multi-Platform: Supports both browser and Node.js environments
• 👥 All Worker Types: Web Workers, Service Workers, Shared Workers, Audio Worklets, Paint Worklets
• 📦 Self-Contained: Bundles all worker dependencies into base64 data URLs
• ⚡ Lazy Loading: Workers only load when actually instantiated
• 🎯 Smart Detection: Automatically detects worker types from filenames
• 🔧 Configurable: Extensive options for customization
• 📘 TypeScript Support: First-class TypeScript support
• 🎛️ Service Worker Integration: Auto-registration with customizable scope
• 🔍 Verbose Logging: Detailed build information when needed

Installation

npm install rollup-plugin-worker64 --save-dev
# or
yarn add rollup-plugin-worker64 --dev
# or
pnpm add rollup-plugin-worker64 --save-dev

Quick Start

// rollup.config.js
import worker64 from 'rollup-plugin-worker64';

export default {
  input: 'src/index.js',
  plugins: [
    worker64(), // That's it! Zero configuration needed
  ],
  output: { dir: 'dist', format: 'es' },
};

How It Works

The plugin automatically detects this pattern in your code:

// Before (your source code)
const worker = new Worker(new URL('./my-worker.js', import.meta.url));

And transforms it to:

// After (built output)
const worker = new Worker((await import('./my-worker.js')).url);

The my-worker.js file gets replaced with:

// Generated my-worker.js
export const url =
  'data:application/javascript;base64,UkdWMGRTaGlJSEJoWTJ0bFpH...';

Configuration Options

worker64({
  sourceDir: 'src', // Source directory containing worker files
  sourceExtension: '.ts', // Source file extension (.ts, .js)
  targetExtension: '.js', // Target extension in import URLs
  platform: 'auto', // Target platform: 'auto', 'browser', 'node'
  bundleFormat: 'iife', // Output format (iife, es, cjs)
  tsconfig: './tsconfig.json', // TypeScript config file
  minify: true, // Enable minification
  verbose: false, // Enable detailed logging
  outputDir: 'build', // Debug output directory (disables cleanup)
  workerPlugins: null, // Custom plugins (null = use defaults)
  serviceWorker: {
    // Service Worker specific options
    scope: '/', // Registration scope
    autoRegister: true, // Auto-register service workers
  },
});

Worker Types Support

The plugin automatically detects worker types based on filename patterns:

• Web Workers: worker.js, web-worker.js, *.worker.js
• Service Workers: service-worker.js, sw.js, *.sw.js
• Shared Workers: shared-worker.js, *.shared.js
• Audio Worklets: audio-worklet.js, *.worklet.js
• Paint Worklets: paint-worklet.js, *.paint.js

Examples

TypeScript Project

import worker64 from 'rollup-plugin-worker64';
import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/index.ts',
  plugins: [
    typescript(),
    worker64(), // Uses TypeScript defaults
  ],
  output: { dir: 'dist', format: 'es' },
};

Node.js Target

import worker64 from 'rollup-plugin-worker64';

export default {
  input: 'src/index.js',
  plugins: [
    worker64({
      platform: 'node', // Generates worker_threads compatible code
      sourceExtension: '.js',
    }),
  ],
  output: { dir: 'dist', format: 'cjs' },
};

Service Worker with Auto-Registration

import worker64 from 'rollup-plugin-worker64';

export default {
  input: 'src/index.js',
  plugins: [
    worker64({
      serviceWorker: {
        scope: '/app/',
        autoRegister: true, // Automatically registers service workers
      },
    }),
  ],
  output: { dir: 'dist', format: 'es' },
};

Custom Worker Plugins

import worker64 from 'rollup-plugin-worker64';

export default {
  input: 'src/index.ts',
  plugins: [
    worker64({
      workerPlugins: [
        typescript({ tsconfig: './tsconfig.worker.json' }),
        resolve({ preferBuiltins: false }),
        commonjs(),
        // Your custom plugins here
      ],
    }),
  ],
  output: { dir: 'dist', format: 'es' },
};

Verbose Logging for Debugging

import worker64 from 'rollup-plugin-worker64';

export default {
  input: 'src/index.ts',
  plugins: [
    worker64({
      verbose: true, // Enable detailed build information
      outputDir: './debug-workers', // Keep temp files for inspection
    }),
  ],
  output: { dir: 'dist', format: 'es' },
};

Advanced Features

Dependency Bundling

The plugin automatically bundles all worker dependencies:

// worker.js - imports are automatically bundled
import { Vector3 } from 'three';
import { calculatePhysics } from './physics-utils.js';

self.onmessage = (event) => {
  const result = calculatePhysics(new Vector3(event.data));
  self.postMessage(result);
};

Platform Detection

Automatically generates appropriate code for your target platform:

• Browser: Uses native Worker APIs with data URLs
• Node.js: Uses worker_threads module with Buffer encoding
• Auto: Detects based on environment variables

Service Worker Auto-Registration

Service workers can be automatically registered:

// Your code
const sw = new Worker(new URL('./service-worker.js', import.meta.url));

// Generated code (when autoRegister: true)
const sw = await (async () => {
  const registration = await navigator.serviceWorker.register(dataUrl, {
    scope: '/',
  });
  return registration;
})();

Development Workflow

The plugin includes development-friendly features:

# Format code
npm run format

# Lint code
npm run lint

# Run tests
npm run test

# Full check (format + lint + test)
npm run check

Benefits

• Eliminates complex multi-step builds - No more manual worker bundling
• Self-contained distribution - Perfect for npm libraries
• Lazy loading - Reduces main bundle size
• Framework agnostic - Works with React, Vue, vanilla JS, etc.
• Dependency bundling - Automatically includes Three.js, etc. in workers
• Multi-platform support - Works in browsers and Node.js
• All worker types - Comprehensive support for modern web workers

License

rollup-plugin-worker64 is created by Felix Z. This project is licensed under the MIT License. For more details, see the LICENSE file in this repository.