worklet-loader

2.0.0 verified Sat Apr 25 auth: no javascript deprecated

Webpack loader that imports scripts as URLs for use with worklet modules (AudioWorklet, PaintWorklet, AnimationWorklet, etc.). Version 2.0.0 is the latest stable release. It is explicitly a fork of worker-loader and the maintainer advises caution as worker-specific behaviors may break worklets. Only works with webpack 3 or 4. No active development; likely obsolete once worker-loader supports worklets natively. Supports inline as Blob, custom filenames, and public path overrides.

Common errors

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause The file does not match the test pattern in webpack config, or the loader is not applied.

fix

Ensure your webpack config has a rule with test: /\.worklet\.js$/ and loader: 'worklet-loader'. Or use inline loader syntax: import url from 'worklet-loader!./file.js';

error Cannot find module 'worklet-loader' ↓

cause worklet-loader is not installed as a devDependency.

fix

Run npm install --save-dev worklet-loader

Warnings

deprecated Package is a fork of worker-loader and the author advises against using it. worker-loader may natively support worklets in the future. ↓

fix Use worker-loader if you need worklet support, or wait for official worklet support.

gotcha The loader only works with webpack 3 or 4. Not compatible with webpack 5. ↓

fix Use webpack 4 or consider an alternative loader for webpack 5.

gotcha When using TypeScript, you must declare a module for the worklet files, otherwise TypeScript will not recognize the import. ↓

fix Add a custom declaration file (e.g., typings/custom.d.ts) with declare module '*.worklet.ts' { const exportString: string; export default exportString; }

gotcha The inline option creates a Blob URL, which may not work in some CSP (Content Security Policy) environments that restrict blob: URLs. ↓

fix Avoid inline: true if your site has strict CSP, or adjust CSP to allow blob: URLs.

Install

npm install worklet-loader

yarn add worklet-loader

pnpm add worklet-loader

Imports

default export (URL string)
wrong
```
import workletUrl from './worklet.js';
```
correct
```
import workletUrl from 'worklet-loader!./worklet.js';
```
Worklet is loaded via inline loader syntax or webpack config rule. The default export is a string URL or Blob URL.

TypeScript declaration

wrong

declare module '*.worklet.js' { const exportString: string; export default exportString; }

correct

declare module '*.worklet.ts' { const exportString: string; export default exportString; }

The declaration must match the file extension used (e.g., .worklet.ts if using TypeScript).

CommonJS require

wrong

const workletUrl = require('./worklet.js');

correct

const workletUrl = require('worklet-loader!./worklet.js');

When using require(), you must include the loader prefix.

Quickstart

Configures webpack to process .worklet.js files with worklet-loader, then imports a worklet file and registers it with AudioWorklet.

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

// App.js
import workletUrl from './file.worklet.js';

const audioCtx = new AudioContext();
audioCtx.audioWorklet.addModule(workletUrl).then(() => {
  console.log('Worklet registered');
});