worker-url

1.1.0 verified Sat Apr 25 auth: no javascript

A webpack v5 plugin and helper library to generate URLs for Web Workers and AudioWorklets. Version 1.1.0, released under MIT license. Unlike native webpack 5 worker support which creates Worker instances directly, worker-url gives you a URL object that can be used with both Worker and AudioWorklet. Also solves the missing Worklet support in webpack 5 (github issue #11543). Ships TypeScript type definitions. Peer dependency on webpack >=5.0.0. Maintained by a single developer, low release cadence.

Common errors

error Cannot find module 'worker-url/plugin' ↓

cause Plugin is imported from incorrect path or missing export in older version.

fix

Ensure you import WorkerUrlPlugin from 'worker-url/plugin' (not 'worker-url'). Check if package is installed correctly.

error TypeError: (intermediate value).addModule is not a function ↓

cause Attempting to use WorkerUrl with AudioWorklet.addModule but the URL object is used incorrectly.

fix

WorkerUrl returns a URL (or string) that can be passed directly to addModule. Example: audioContext.audioWorklet.addModule(workerUrl).

error Module parse failed: Unexpected character '#' ↓

cause Webpack configuration missing WorkerUrlPlugin or using unsupported syntax (e.g., dynamic import not handled).

fix

Add new WorkerUrlPlugin() to webpack plugins and ensure your webpack config is set up correctly for workers.

Warnings

gotcha WorkerUrlPlugin must be added to webpack plugins or WorkerUrl will generate an incorrect URL. ↓

fix Add `new WorkerUrlPlugin()` to your webpack plugins configuration.

breaking worker-url requires webpack >=5.0.0. Not compatible with webpack 4. ↓

fix Upgrade to webpack 5 or use alternative worker-loader.

deprecated The `WorkerUrl` constructor options `name` and `customPath` signature may change in future versions. ↓

fix Check the changelog before upgrading major versions.

Install

npm install worker-url

yarn add worker-url

pnpm add worker-url

Imports

WorkerUrl
wrong
```
const { WorkerUrl } = require('worker-url');
```
correct
```
import { WorkerUrl } from 'worker-url'
```
Default import is not available; named import is required. CommonJS require works but is not the preferred pattern.
WorkerUrlPlugin
wrong
```
import { WorkerUrlPlugin } from 'worker-url'
```
correct
```
import { WorkerUrlPlugin } from 'worker-url/plugin'
```
The plugin is in a separate subpath export 'worker-url/plugin'. Direct import from 'worker-url' does not include it.
WorkerUrl type
wrong
```
import { WorkerUrl } from 'worker-url' (used as type only)
```
correct
```
import type { WorkerUrl } from 'worker-url'
```
TypeScript users can use type-only import to avoid bundling runtime code. The library ships TypeScript definitions.

Quickstart

Configures webpack plugin and creates a Worker using WorkerUrl helper.

// webpack.config.js
const { WorkerUrlPlugin } = require('worker-url/plugin');
module.exports = {
  output: { publicPath: '/' },
  plugins: [new WorkerUrlPlugin()]
};

// index.js
import { WorkerUrl } from 'worker-url';
const workerUrl = new WorkerUrl(new URL('./worker.js', import.meta.url), { name: 'myworker' });
const worker = new Worker(workerUrl);
// For worklet:
// audioContext.audioWorklet.addModule(workerUrl);