tsdown-plugin-worker

A tsdown plugin for handling Web Workers and SharedWorkers. Supports both ?worker query imports and the standard ES modules new URL() pattern.

Installation

npm install tsdown-plugin-worker
# or
yarn add tsdown-plugin-worker
# or
bun add tsdown-plugin-worker

Quick Start

tsdown.config.ts

import { defineConfig } from "tsdown";
import workerPlugins from "tsdown-plugin-worker";

export default defineConfig({
  plugins: [workerPlugins({ format: "es" })],
});

tsconfig.json

{
  "compilerOptions": {
    "types": ["tsdown-plugin-worker/types"]
  }
}

Usage Patterns

1. Query Import Pattern (?worker)

Import a worker file using the ?worker query suffix:

import MyWorker from "./worker.ts?worker";

const worker = new MyWorker();
worker.postMessage("Hello");

2. SharedWorker Query Import (?sharedworker)

For SharedWorkers, use the ?sharedworker query:

import MySharedWorker from "./worker.ts?sharedworker";

const sharedWorker = new MySharedWorker();
sharedWorker.port.postMessage("Hello");

3. Inline Workers (?worker&inline)

Bundle worker code inline as a Blob (no separate file):

import InlineWorker from "./worker.ts?worker&inline";

const worker = new InlineWorker();
worker.postMessage("Hello");

4. Standard ES Modules new URL() Pattern

Use the standard browser pattern with automatic bundling:

const worker = new Worker(new URL("./worker.ts", import.meta.url));

5. SharedWorker with new URL()

const sharedWorker = new SharedWorker(new URL("./worker.ts", import.meta.url));

6. Workers with Options

Pass worker options when using new URL():

const worker = new Worker(new URL("./worker.ts", import.meta.url), {
  type: "module",
});

7. Workers with Imports

Workers can import other modules - they'll be bundled automatically:

// worker.ts
import { processData } from "./utils";

self.onmessage = (event) => {
  const result = processData(event.data);
  self.postMessage(result);
};

// main.ts
import MyWorker from "./worker.ts?worker";

const worker = new MyWorker();

8. Package Worker Imports

You can import workers from packages (including ?worker&inline):

import EditorWorker from "monaco-editor/esm/vs/editor/editor.worker.js?worker";
// or
import InlineEditorWorker from "monaco-editor/esm/vs/editor/editor.worker.js?worker&inline";

const worker = new EditorWorker();

Warning

Package worker imports can cause dependencies to be internalized into your build output. If you expected those dependencies to stay external for downstream bundlers, review your output carefully before publishing libraries.

Format Options

ES Modules (format: 'es')

Default format. Workers are loaded as ES modules:

workerPlugins({ format: "es" });

IIFE Format (format: 'iife')

For IIFE output with classic script workers:

workerPlugins({ format: "iife" });

Advanced: Individual Plugins

For fine-grained control, use individual plugins:

import {
  workerQueryPlugin, // Handles ?worker and ?sharedworker imports
  workerNewUrlPlugin, // Handles new URL() patterns
  workerPostPlugin, // Post-processing for IIFE format
} from "tsdown-plugin-worker";

export default defineConfig({
  plugins: [
    workerQueryPlugin({ format: "iife" }),
    workerNewUrlPlugin({ format: "iife" }),
    workerPostPlugin({ format: "iife" }),
  ],
});

Configuration Options

interface WorkerPluginOptions {
  format: "es" | "iife"; // Output format
  rolldownOptions?: RolldownOptions; // Custom rolldown options for worker bundling
}