audio-worklet-loader

1.1.0 verified Sat Apr 25 auth: no javascript

Webpack loader for Audio Worklet processors, enabling bundling and module resolution for .worklet.js and .worklet.ts files. Version 1.1.0 is stable but explicitly does not support Webpack 4. It can inline worklet code as a Blob to avoid separate chunks, with fallback modes for bundling. This loader fills a niche for web audio applications needing AudioWorklet support in Webpack 5, similar to worker-loader but for audio worklets.

Common errors

error Error: Module parse failed: Unexpected token (1:0) in ... The loader may need to be configured. ↓

cause The rule for .worklet.js files is not correctly defined or the loader is not applied.

fix

Ensure webpack config has a rule: { test: /\.worklet\.js$/, loader: 'audio-worklet-loader' }

error TypeError: Cannot read properties of undefined (reading 'addModule') - workletUrl is undefined ↓

cause The inline import returned undefined because inline option 'no-fallback' was used but the file wasn't actually inlined (maybe misconfiguration).

fix

Check that the rule matches the file extension and the loader is applied. Use 'fallback' mode or omit inline to always get a URL.

error Uncaught DOMException: Failed to execute 'addModule' on 'AudioWorklet': '...url...' is not a valid URL. ↓

cause The worklet URL returned by the loader is not a proper blob or file URL; likely the loader didn't process the file.

fix

Verify the loader is applied in webpack config and the import path includes the loader prefix: 'audio-worklet-loader!./file.worklet.js'

Warnings

breaking Webpack 4 is not supported. Do not attempt to use this loader with Webpack 4; it will fail. ↓

fix Use Webpack 5 (>=5.0.0) exclusively.

gotcha The loader must appear before ts-loader in the rules array when processing .worklet.ts files, otherwise TypeScript compilation will break. ↓

fix Order rules so audio-worklet-loader is first for .worklet.ts files, then ts-loader for other .ts files.

gotcha Inline option values are case-sensitive strings: 'fallback' or 'no-fallback'. Using boolean true or misspelling will cause the option to be ignored (no inlining). ↓

fix Pass { inline: 'no-fallback' } in options object.

deprecated The require() usage in older examples is not technically deprecated but ESM imports are preferred. The loader works with both import and require. ↓

fix Use import workletURL from 'audio-worklet-loader!./file.worklet.js'; for modern ES modules.

Install

npm install audio-worklet-loader

yarn add audio-worklet-loader

pnpm add audio-worklet-loader

Imports

default (import from worklet file)
wrong
```
import workletURL from './processor.worklet.js';
```
correct
```
import workletURL from 'audio-worklet-loader!./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

wrong

module.exports = { module: { rules: [ { test: /\.worklet\.js$/, use: 'audio-worklet-loader' } ] } };

correct

module.exports = { module: { rules: [ { test: /\.worklet\.js$/, loader: '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
wrong
```
options: { inline: true }
```
correct
```
loader: 'audio-worklet-loader', options: { inline: 'no-fallback' }
```
The inline option accepts string 'fallback' or 'no-fallback', not boolean. Missing or invalid value defaults to undefined (no inlining).

Quickstart

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();