esbuild-plugin-webworker

0.0.3 verified Fri May 01 auth: no javascript

An ESbuild plugin for handling Web Workers by marking imports with `?worker` query suffix. v0.0.3 (sparse releases). Supports inlining worker code (default) or outputting separate files. Requires ESbuild ≥0.18.0 and Node ≥14.0.0. Differentiators: simple query-based syntax, automatic bundling and minification, TypeScript support. Limited community adoption and maintenance.

Common errors

error Error: The plugin "esbuild-plugin-webworker" is not compatible with the current version of esbuild. Required esbuild >= 0.18.0 ↓

cause Installed esbuild version is too low (<0.18.0).

fix

Run npm install esbuild@latest to update to a compatible version.

error SyntaxError: Cannot use import statement outside a module ↓

cause Using import syntax in a CommonJS file without enabling ESM.

fix

Set "type": "module" in your package.json or rename the file to .mjs.

error TypeError: webworker is not a function ↓

cause Default import used with CommonJS require; plugin exports ES module default.

fix

Switch to ESM import or use dynamic import: import('esbuild-plugin-webworker').then(m => m.default()).

Warnings

gotcha Plugin only supports ESM; do not use require() to import the plugin or worker modules. ↓

fix Use import syntax in an ES module context (add 'type':'module' in package.json or use .mjs extension).

deprecated Node.js v14 is minimum but v14 is end-of-life; consider upgrading to Node v18+. ↓

fix Update Node to v18 or higher.

breaking Requires esbuild v0.18.0+; older versions will fail with unknown plugin error. ↓

fix Upgrade esbuild to >=0.18.0

gotcha Default inline:true may cause large bundles if worker code is substantial; memory usage can be high. ↓

fix Set inline:false and specify an out directory to generate separate worker files.

Install

npm install esbuild-plugin-webworker

yarn add esbuild-plugin-webworker

pnpm add esbuild-plugin-webworker

Imports

default

wrong

const webworker = require('esbuild-plugin-webworker')

correct

import webworker from 'esbuild-plugin-webworker'

Plugin is ESM only, does not support CommonJS require.

createWorker
wrong
```
import createWorker from './fib_worker'
```
correct
```
import createWorker from './fib_worker?worker'
```
Worker files must be imported with the `?worker` query suffix to be detected by the plugin.

type PluginOptions

import type { PluginOptions } from 'esbuild-plugin-webworker'

TypeScript types are shipped with the package.

Quickstart

Sets up esbuild with the webworker plugin, builds a main file that imports a worker script via `?worker`, and runs Fibonacci computation in a worker.

// build.js
import { build } from 'esbuild';
import webworker from 'esbuild-plugin-webworker';

build({
  entryPoints: ['src/main.ts'],
  outfile: 'dist/bundle.js',
  bundle: true,
  plugins: [webworker()],
  format: 'esm',
}).catch(() => process.exit(1));

// src/main.ts
import createWorker from './fib.worker?worker';

const worker = createWorker();
const promise = new Promise<number>((resolve) => {
  worker.onmessage = (e) => resolve(e.data);
});
worker.postMessage(40);
console.log(await promise);