or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-worker-loader

Webpack loader module for integrating Web Workers into webpack-bundled applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/worker-loader@3.0.x

To install, run

npx @tessl/cli install tessl/npm-worker-loader@3.0.0

index.mddocs/

Worker Loader

Worker Loader is a webpack loader that enables developers to easily integrate Web Workers into their webpack-bundled applications. It provides flexible configuration options for worker instantiation, customizable filename patterns, inline mode for embedding workers as BLOBs, and seamless integration with modern JavaScript features.

Package Information

  • Package Name: worker-loader
  • Package Type: npm (webpack loader)
  • Language: JavaScript
  • Installation: npm install worker-loader --save-dev
  • Peer Dependencies: webpack@^4.0.0 || ^5.0.0

Core Imports

Worker Loader generates factory functions that can be imported using standard ES modules or CommonJS syntax:

// ES modules (default, when esModule: true)
import Worker from "./my.worker.js";

// CommonJS (when esModule: false)
const Worker = require("./my.worker.js");

// Inline loader syntax (ES modules)
import Worker from "worker-loader!./Worker.js";

// Inline loader syntax (CommonJS)
const Worker = require("worker-loader!./Worker.js");

Core Usage

Worker Loader can be used in two primary ways:

Webpack Configuration

module.exports = {
  module: {
    rules: [
      {
        test: /\.worker\.(c|m)?js$/,
        use: {
          loader: "worker-loader",
          options: {
            // Configuration options
          },
        },
      },
    ],
  },
};

Inline Loader Syntax

import Worker from "worker-loader!./Worker.js";

// With options as query parameters
import Worker from "worker-loader?filename=custom.worker.js!./Worker.js";

Basic Usage

// 1. Create a worker file (e.g., my.worker.js)
// my.worker.js
onmessage = function (event) {
  const workerResult = event.data;
  workerResult.processed = true;
  postMessage(workerResult);
};

// 2. Import and use the worker in your main application
import Worker from "./my.worker.js";

const worker = new Worker();

worker.onmessage = function (event) {
  console.log("Received from worker:", event.data);
};

worker.postMessage({ data: "Hello worker!" });

Capabilities

Worker Instantiation

Creates Web Worker or SharedWorker instances with customizable constructor options.

// Generated worker factory function interface
interface WorkerFactory {
  (): Worker | SharedWorker;
}

// Configuration for worker type
interface WorkerTypeConfig {
  type: string;           // Constructor name (e.g., "Worker", "SharedWorker")
  options?: WorkerOptions; // Worker constructor options
}

interface WorkerOptions {
  type?: "classic" | "module";
  credentials?: "omit" | "same-origin" | "include";
  name?: string;
}

Loader Configuration

Configure the loader behavior through webpack configuration options.

interface WorkerLoaderOptions {
  worker?: string | WorkerTypeConfig;  // Default: "Worker"
  publicPath?: string | ((pathData: any, assetInfo: any) => string);
  filename?: string | ((pathData: any) => string);
  chunkFilename?: string;
  inline?: "no-fallback" | "fallback";
  esModule?: boolean;  // Default: true
}

Worker Option

Specifies the worker constructor type and options.

String format:

{
  worker: "SharedWorker"
}

Object format:

{
  worker: {
    type: "SharedWorker",
    options: {
      type: "classic",
      credentials: "omit",
      name: "my-custom-worker-name"
    }
  }
}

PublicPath Option

Controls the public URL path for worker files.

String format:

{
  publicPath: "/scripts/workers/"
}

Function format:

{
  publicPath: (pathData, assetInfo) => {
    return `/scripts/${pathData.hash}/workers/`;
  }
}

Filename Option

Customizes the filename pattern for worker entry chunks.

String format:

{
  filename: "[name].[contenthash].worker.js"
}

Function format:

{
  filename: (pathData) => {
    if (/\.worker\.(c|m)?js$/i.test(pathData.chunk.entryModule.resource)) {
      return "[name].custom.worker.js";
    }
    return "[name].js";
  }
}

ChunkFilename Option

Sets the filename pattern for worker non-entry chunks.

{
  chunkFilename: "[id].[contenthash].worker.js"
}

Inline Option

Enables inline worker mode using Blob URLs to avoid cross-origin issues.

{
  inline: "fallback"  // Creates fallback file for unsupported browsers
}
{
  inline: "no-fallback"  // Inline only, no fallback file
}

ESModule Option

Controls whether generated code uses ES modules or CommonJS syntax.

{
  esModule: false  // Use CommonJS: module.exports = function...
}

Cross-Origin Support

Handle cross-origin restrictions with inline workers.

// Runtime inline worker function (from runtime/inline.js)
// Creates workers using Blob URLs with progressive fallback strategies
function inlineWorker(
  content: string,           // Worker source code content
  workerConstructor: string, // Constructor name ("Worker", "SharedWorker", etc.)
  workerOptions?: object,    // Worker constructor options
  url?: string              // Fallback URL for unsupported environments
): Worker | SharedWorker

// Fallback strategy:
// 1. Try Blob API with URL.createObjectURL()
// 2. Try data: URL with encoded content
// 3. Fall back to external URL if provided
// 4. Throw error if no fallback available

Usage with inline option:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.worker\.js$/,
        loader: "worker-loader",
        options: {
          inline: "fallback"
        }
      }
    ]
  }
};

// Your application code remains the same
import Worker from "./file.worker.js";
const worker = new Worker();

TypeScript Integration

For TypeScript projects, define custom module declarations.

// typings/worker-loader.d.ts
declare module "worker-loader!*" {
  class WebpackWorker extends Worker {
    constructor();
  }
  export default WebpackWorker;
}

TypeScript usage:

import Worker from "worker-loader!./Worker.ts";

const worker = new Worker();
worker.postMessage({ data: "Hello from TypeScript!" });
worker.onmessage = (event) => {
  console.log("Worker response:", event.data);
};

Generated Code Patterns

The loader generates different code patterns based on configuration:

Standard Worker Factory (esModule: true)

export default function Worker_fn() {
  return new Worker(__webpack_public_path__ + "worker.worker.js");
}

CommonJS Worker Factory (esModule: false)

module.exports = function Worker_fn() {
  return new Worker(__webpack_public_path__ + "worker.worker.js");
}

SharedWorker with Options

export default function SharedWorker_fn() {
  return new SharedWorker(
    __webpack_public_path__ + "worker.worker.js",
    { "type": "classic", "name": "my-worker" }
  );
}

Inline Worker Factory

import worker from "!!./runtime/inline.js";

export default function Worker_fn() {
  return worker(
    /* worker source code */,
    "Worker",
    /* worker options */,
    /* fallback url */
  );
}

Advanced Examples

Babel Integration

For ES6+ features in workers, combine with babel-loader:

module.exports = {
  module: {
    rules: [
      {
        test: /\.worker\.(c|m)?js$/i,
        use: [
          {
            loader: "worker-loader"
          },
          {
            loader: "babel-loader",
            options: {
              presets: ["@babel/preset-env"]
            }
          }
        ]
      }
    ]
  }
};

Dynamic Worker Creation

Using function-based filename for dynamic naming:

module.exports = {
  module: {
    rules: [
      {
        test: /\.worker\.js$/,
        loader: "worker-loader",
        options: {
          filename: (pathData) => {
            const workerName = pathData.chunk.entryModule.resource
              .split("/")
              .pop()
              .replace(".worker.js", "");
            return `workers/${workerName}.[contenthash].js`;
          }
        }
      }
    ]
  }
};

WASM Worker Support

Worker Loader automatically handles WebAssembly modules in workers:

// worker-with-wasm.worker.js
import wasmModule from "./calculator.wasm";

onmessage = async function(event) {
  const wasm = await wasmModule();
  const result = wasm.calculate(event.data.numbers);
  postMessage({ result });
};

Error Handling

Worker Loader handles various error scenarios:

  1. Browser Compatibility: When inline: "fallback" is used, unsupported browsers fall back to external files
  2. Cross-Origin Issues: Inline mode creates Blob URLs to bypass CORS restrictions
  3. Build Failures: Invalid worker code causes webpack compilation errors with clear messages
  4. Runtime Errors: Standard Web Worker error handling applies to generated workers
const worker = new Worker();

worker.onerror = function(error) {
  console.error("Worker error:", error);
};

worker.onmessageerror = function(error) {
  console.error("Worker message error:", error);
};