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–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default (import from worklet file)
✓ import workletURL from 'audio-worklet-loader!./processor.worklet.js';
✗ import workletURL from './processor.worklet.js';
The loader must be applied via inline syntax or webpack config rule; otherwise the import returns the raw module, not the worklet URL.
webpack rule for .worklet.js
✓ module.exports = { module: { rules: [ { test: /\.worklet\.js$/, loader: 'audio-worklet-loader' } ] } };
✗ module.exports = { module: { rules: [ { test: /\.worklet\.js$/, use: 'audio-worklet-loader' } ] } };
Use 'loader' not 'use' in rule; 'use' is for multiple loaders and may cause unexpected behavior. Also ensure loader is applied before ts-loader for .worklet.ts files.
options inline
✓ loader: 'audio-worklet-loader', options: { inline: 'no-fallback' }
✗ options: { inline: true }
The inline option accepts string 'fallback' or 'no-fallback', not boolean. Missing or invalid value defaults to undefined (no inlining).
Minimal Webpack config using audio-worklet-loader with inline option, and an async function that loads an AudioWorklet from the bundled URL.
// webpack.config.js
const path = require('path');
module.exports = {
entry: './index.js',
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'bundle.js',
},
module: {
rules: [
{
test: /\.worklet\.js$/i,
loader: 'audio-worklet-loader',
options: { inline: 'no-fallback' },
},
],
},
target: 'web',
mode: 'development',
};
// index.js
async function main() {
const audioCtx = new AudioContext();
const workletUrl = require('audio-worklet-loader!./random-noise.worklet.js');
await audioCtx.audioWorklet.addModule(workletUrl);
const node = new AudioWorkletNode(audioCtx, 'random-noise');
node.connect(audioCtx.destination);
}
main();
Errors
Common errors & fixes
Error: Module parse failed: Unexpected token (1:0) in ... The loader may need to be configured.
The rule for .worklet.js files is not correctly defined or the loader is not applied.
fixEnsure webpack config has a rule: { test: /\.worklet\.js$/, loader: 'audio-worklet-loader' } TypeError: Cannot read properties of undefined (reading 'addModule') - workletUrl is undefined
The inline import returned undefined because inline option 'no-fallback' was used but the file wasn't actually inlined (maybe misconfiguration).
fixCheck that the rule matches the file extension and the loader is applied. Use 'fallback' mode or omit inline to always get a URL.
Uncaught DOMException: Failed to execute 'addModule' on 'AudioWorklet': '...url...' is not a valid URL.
The worklet URL returned by the loader is not a proper blob or file URL; likely the loader didn't process the file.
fixVerify the loader is applied in webpack config and the import path includes the loader prefix: 'audio-worklet-loader!./file.worklet.js'
Audit
Dependencies
webpackrequiredPeer dependency required; loader only works with Webpack 5, Webpack 4 not supported.