worker-file-loader

worker loader module for webpack

this module is forked from worker-loader and customized so that the url of the created worker is returned to create service-workers or workers with the url.

Requirements

This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

To begin, you'll need to install worker-file-loader:

$ npm install worker-file-loader --save-dev

window is not defined-error in development

This is a known error and eventually fixed, when the target: "universal"-feature lands in webpack (#6525).

To fix the error in the meanwhile, you can add this to your webpack-config:

const isDevelopment = process.env.NODE_ENV === 'development';
module.exports = {
  // ...
  output: {
    // ...
    globalObject: isDevelopment
      ? "(typeof self !== 'undefined' ? self : this)"
      : undefined,
  },
};

Inlined

// App.js
import Worker from 'worker-file-loader!./Worker.js';

Config

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

// App.js
import workerUrl from './file.worker.js';

const worker = new Worker(workerUrl);

worker.postMessage({ a: 1 });
worker.onmessage = function(event) {};

worker.addEventListener('message', function(event) {});

And run webpack via your preferred method.

Options

fallback

Type: Boolean Default: false

Require a fallback for non-worker supporting environments

// webpack.config.js
{
  loader: 'worker-file-loader';
  options: {
    fallback: false;
  }
}

name

Type: String Default: [hash].worker.js

To set a custom name for the output script, use the name parameter. The name may contain the string [hash], which will be replaced with a content dependent hash for caching purposes. When using name alone [hash] is omitted.

// webpack.config.js
{
  loader: 'worker-file-loader',
  options: { name: 'WorkerName.[hash].js' }
}

publicPath

Type: String Default: null

Overrides the path from which worker scripts are downloaded. If not specified, the same public path used for other webpack assets is used.

// webpack.config.js
{
  loader: 'worker-file-loader';
  options: {
    publicPath: '/scripts/workers/';
  }
}

Examples

The worker file can import dependencies just like any other file:

// Worker.js
const _ = require('lodash');

const obj = { foo: 'foo' };

_.has(obj, 'foo');

// Post data to parent thread
self.postMessage({ foo: 'foo' });

// Respond to message from parent thread
self.addEventListener('message', (event) => console.log(event));

Integrating with ES2015 Modules

Note: You can even use ES2015 Modules if you have the babel-loader configured.

// Worker.js
import _ from 'lodash';

const obj = { foo: 'foo' };

_.has(obj, 'foo');

// Post data to parent thread
self.postMessage({ foo: 'foo' });

// Respond to message from parent thread
self.addEventListener('message', (event) => console.log(event));

Integrating with TypeScript

To integrate with TypeScript, you will need to define a custom module for the exports of your worker

// typings/custom.d.ts
declare module 'worker-file-loader!*' {
  const url: string;

  export default url;
}

// Worker.ts
const ctx: Worker = self as any;

// Post data to parent thread
ctx.postMessage({ foo: 'foo' });

// Respond to message from parent thread
ctx.addEventListener('message', (event) => console.log(event));

// App.ts
import workerUrl from 'worker-file-loader!./Worker';

const worker = new Worker(workerUrl);

worker.postMessage({ a: 1 });
worker.onmessage = (event) => {};

worker.addEventListener('message', (event) => {});

Cross-Origin Policy

WebWorkers are restricted by a same-origin policy, so if your webpack assets are not being served from the same origin as your application, their download may be blocked by your browser. This scenario can commonly occur if you are hosting your assets under a CDN domain. Even downloads from the webpack-dev-server could be blocked. There are two workarounds:

Firstly, you can inline the worker as a blob instead of downloading it as an external script via the inline parameter (this option is removed for this loader)

Secondly, you may override the base download URL for your worker script via the publicPath option

// App.js
// This will result in `/workers/file.worker.js`
import workerUrl from './file.worker.js';

// webpack.config.js
{
  loader: 'worker-file-loader';
  options: {
    publicPath: '/workers/';
  }
}

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT