Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WorkerUrl
✓ import { WorkerUrl } from 'worker-url'
✗ const { WorkerUrl } = require('worker-url');
Default import is not available; named import is required. CommonJS require works but is not the preferred pattern.
WorkerUrlPlugin
✓ import { WorkerUrlPlugin } from 'worker-url/plugin'
✗ import { WorkerUrlPlugin } from 'worker-url'
The plugin is in a separate subpath export 'worker-url/plugin'. Direct import from 'worker-url' does not include it.
WorkerUrl type
✓ import type { WorkerUrl } from 'worker-url'
✗ import { WorkerUrl } from 'worker-url' (used as type only)
TypeScript users can use type-only import to avoid bundling runtime code. The library ships TypeScript definitions.
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);
Errors
Common errors & fixes
Cannot find module 'worker-url/plugin'
Plugin is imported from incorrect path or missing export in older version.
fixEnsure you import `WorkerUrlPlugin` from 'worker-url/plugin' (not 'worker-url'). Check if package is installed correctly.
TypeError: (intermediate value).addModule is not a function
Attempting to use WorkerUrl with AudioWorklet.addModule but the URL object is used incorrectly.
fixWorkerUrl returns a URL (or string) that can be passed directly to `addModule`. Example: `audioContext.audioWorklet.addModule(workerUrl)`.
Module parse failed: Unexpected character '#'
Webpack configuration missing WorkerUrlPlugin or using unsupported syntax (e.g., dynamic import not handled).
fixAdd `new WorkerUrlPlugin()` to webpack plugins and ensure your webpack config is set up correctly for workers.
Audit
Dependencies
webpackrequiredpeer dependency required for the plugin to function