#Web Workers

This chapter introduces how to configure and use Web Workers in Rsbuild project.

#Use Web Workers

#Import with constructors

Rspack provides built-in support for Web Workers, which means you can use Web Workers directly in Rsbuild projects without needing any Loaders.

For example, create a file called worker.js:

self.onmessage = (event) => {
  const result = event.data * 2;
  self.postMessage(result);
};

Then use this worker in the main thread:

const worker = new Worker(new URL('./worker.js', import.meta.url));

worker.onmessage = (event) => {
  console.log('The results from Workers:', event.data);
};

worker.postMessage(10);

Rspack supports multiple Worker syntaxes by default. See Rspack - Web Workers for more information.

#Using worker-loader

If your project already uses worker-loader, or you want to use the inline and other features provided by worker-loader, you can use worker-rspack-loader as an alternative to worker-loader in Rsbuild projects.

export default {
  tools: {
    rspack: {
      resolveLoader: {
        alias: {
          // Modify the resolution of worker-loader in the inline loader
          // such as `worker-loader!pdfjs-dist/es5/build/pdf.worker.js`
          'worker-loader': require.resolve('worker-rspack-loader'),
        },
      },
      module: {
        rules: [
          {
            test: /\.worker\.js$/,
            loader: 'worker-rspack-loader',
          },
        ],
      },
    },
  },
};

When using worker-rspack-loader, you need to use import to load the Web Worker file, instead of new Worker('/path/to/worker.js').

import Worker from './file.worker.js';

const worker = new Worker();

worker.postMessage({ a: 1 });

worker-loader is no longer maintained. If you don't need to inline Web Workers, we recommend using the new Worker() syntax.

#Loading scripts from remote URLs

By default, the worker script will be emitted as a separate chunk. This script supports uploading to CDN, but must obey the same-origin policy.

If you want your worker scripts to be accessible across domains, a common solution is to load them via importScripts (not subject to CORS). You can refer to the following code:

// https://github.com/jantimon/remote-web-worker
import 'remote-web-worker';

const worker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'classic',
});

worker.onmessage = (event) => {
  console.log('The results from Workers:', event.data);
};

worker.postMessage(10);

For detailed discussions on cross-domain issues, please refer to Discussions - webpack 5 web worker support for CORS?

#Browser compatibility

When your application includes both main-thread code and Web Workers created with new Worker, note that Web Workers run in isolated threads and do not share the main-thread environment. As a result, Rsbuild’s polyfill entry mode does not apply to Web Workers. In this case, it’s recommended to use the usage mode to inject the required polyfills directly into each Web Worker.

export default {
  output: {
    polyfill: 'usage',
  },
};

#Standalone build

Rsbuild supports standalone building of Web Workers bundles. When you need to configure independent build options for Web Workers or provide Web Workers for use by other applications, you can use the following methods.

Set Rsbuild's output.target configuration option to 'web-worker' to generate build artifacts that run in Worker threads.

export default {
  output: {
    target: 'web-worker',
  },
};

Use environments to build both Web Workers and the main application simultaneously:

export default {
  environments: {
    web: {
      // Build configuration for the main application
    },
    webWorker: {
      // Build configuration for Web Workers
      output: {
        target: 'web-worker',
      },
    },
  },
};