import WebpackLicense from '@components/WebpackLicense'; import { ApiMeta, Stability } from '@components/ApiMeta.tsx'; import { Tabs, Tab } from '@theme';

Web Workers

Rspack provides built-in support for Web Workers, which means you don't need any loader to use Web Workers directly.

Usage

Basic Worker creation syntax:

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

You can customize the Worker's chunk name through the name property (the property value must be statically analyzable). This name will replace the [name] placeholder in the generated chunk filename:

new Worker(new URL('./worker.js', import.meta.url), {
  name: 'my-worker',
});

:::info This syntax was chosen for its strong standards compliance. It's built on the standard ECMAScript module specification, which means it works seamlessly even without build tools. For example, it runs natively in modern browsers with ES module support. :::

For usage examples, see:

Limitations

Because Rspack relies on static analysis to identify worker usage, it has the following two limitations:
- new Worker and other worker-like APIs can usually also accept a string representation of a URL, but Rspack only supports passing a URL object. In practice, you must pass new URL('./worker.js', import.meta.url).
- Rspack cannot statically analyze variables used in new Worker. For example, the following code will not work:
  js
```
const url = new URL('./path/to/worker.js', import.meta.url);
const worker = new Worker(url);
```
The /* webpackEntryOptions: { filename: "workers/[name].js" } */ magic comment is not supported yet.

Built-in syntax

In addition to new Worker(), Rspack also supports the following built-in forms by default:

new SharedWorker(), see SharedWorker

const sharedWorker = new SharedWorker(
  new URL('./shared-worker.js', import.meta.url),
);
sharedWorker.port.start();

import { Worker } from "worker_threads": commonly used in Node.js environments, see Worker threads

import { Worker } from 'worker_threads';

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

navigator.serviceWorker.register(): used to register Service Workers, see ServiceWorkerContainer

navigator.serviceWorker
  .register(new URL('./sw.js', import.meta.url))
  .then((registration) => {
    console.log('Service worker registration succeeded:', registration);
  });

Custom syntax

Use module.parser.javascript.worker to tell Rspack which expressions should be analyzed as worker-like entry creation:

true keeps the built-in defaults and is equivalent to ['...'].
false disables worker syntax analysis and is equivalent to [].
An array replaces the defaults. Keep '...' in the array if you want to extend the built-in defaults instead of replacing them.

The built-in syntax is implemented using the same mechanism. The '...' placeholder can be expanded to the following entries:

export default {
  module: {
    parser: {
      javascript: {
        worker: [
          'Worker',
          'SharedWorker',
          'navigator.serviceWorker.register()',
          'Worker from worker_threads',
        ],
      },
    },
  },
};

The following rules explain the custom syntax:

A trailing () matches call syntax, while no trailing () matches constructor syntax.
- 'worker' will match new worker(new URL("./worker.js", import.meta.url)).
- 'worker()' will match worker(new URL("./worker.js", import.meta.url)).
Member syntax is also supported, but the root object must be a free variable.
- 'foo.bar' will match new foo.bar(new URL("./worker.js", import.meta.url)).
- 'foo.bar()' will match foo.bar(new URL("./worker.js", import.meta.url)).
Use * to match a root object by its exact variable name. Unlike plain member syntax, the root object here is a declared variable rather than a free variable.
- '*foo.bar()' will match const foo = new WorkletContext(); foo.bar(new URL("./processor.js", import.meta.url)).
- For now, *-prefixed syntax supports only call syntax; constructor syntax such as '*foo.bar' is not supported.
Use from to match an imported binding from an exact ESM source.
- 'Foo from pkg' will match import { Foo } from 'pkg'; new Foo(new URL("./worker.js", import.meta.url)).
- 'default from pkg' will match import Foo from 'pkg'; new Foo(new URL("./worker.js", import.meta.url)).
- 'foo() from pkg' will match import { foo } from 'pkg'; foo(new URL("./worker.js", import.meta.url)).

export default {
  module: {
    parser: {
      javascript: {
        worker: [
          // custom syntax
          'MyWorker',
          'myWorker()',
          'CSS.paintWorklet.addModule()',
          '*audioContext.audioWorklet.addModule()',
          'default from web-worker',
          // extend built-in syntax
          '...',
        ],
      },
    },
  },
};

The following examples show how these custom syntax rules work in practice.

The first few examples are based on the built-in syntax. In practice, you do not need to add them to the config because they are already included in the default '...'. They are shown here only to explain how the custom syntax rules work:

Built-in constructor syntax: Worker and SharedWorker

Worker and SharedWorker are constructors, not functions, so the syntax string does not need trailing ().

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

const sharedWorker = new SharedWorker(
  new URL('./shared-worker.js', import.meta.url),
);

Built-in call syntax: navigator.serviceWorker.register()

This example shows why trailing () matters: register() is a function call, not a constructor.
js
```
await navigator.serviceWorker.register(new URL('./sw.js', import.meta.url));
```

Built-in import syntax: Worker from worker_threads

This example shows the from rule. The import source must match exactly.

import { Worker } from 'worker_threads';

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

The remaining examples show some common patterns in the ecosystem that can be supported through custom syntax:

CSS Worklet

The syntax CSS.paintWorklet.addModule() is a direct member call, so the config string ends with ().

export default {
  module: {
    parser: {
      javascript: {
        worker: [
          'CSS.paintWorklet.addModule()',
          'CSS.layoutWorklet.addModule()',
          'CSS.animationWorklet.addModule()',
          '...',
        ],
      },
    },
  },
};

await CSS.paintWorklet.addModule(
  new URL('./paint-worklet.js', import.meta.url),
);

await CSS.layoutWorklet.addModule(
  new URL('./layout-worklet.js', import.meta.url),
);

await CSS?.animationWorklet?.addModule(
  new URL('./animation-worklet.js', import.meta.url),
);

AudioWorklet

Unlike CSS Worklet, the root object in audioContext.audioWorklet.addModule(...) is not a free variable. It is a variable declared by const audioContext = new AudioContext();, so the custom syntax needs to start with * to indicate that the root object is a declared variable.

export default {
  module: {
    parser: {
      javascript: {
        worker: ['*audioContext.audioWorklet.addModule()', '...'],
      },
    },
  },
};

const audioContext = new AudioContext();

await audioContext.audioWorklet.addModule(
  new URL('./noise-processor.js', import.meta.url),
);

Importing workers from third-party packages.

These examples show how from works with different import styles.

export default {
  module: {
    parser: {
      javascript: {
        worker: [
          'default from web-worker',
          'createWorker() from @myorg/worker',
          '...',
        ],
      },
    },
  },
};

import Worker from 'web-worker';

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

import { createWorker } from '@myorg/worker';

const helperWorker = createWorker(
  new URL('./helper-worker.js', import.meta.url),
);

worker-loader

:::warning worker-loader is provided only as a temporary solution to facilitate project migration to Rspack. It is recommended to use the new Worker() syntax instead. :::

Rspack also supports worker-loader. However, since worker-loader is no longer maintained, please use worker-rspack-loader as a replacement.

Use resolveLoader to replace worker-loader with worker-rspack-loader:

<Tabs> <Tab label="ESM"> ```js title="rspack.config.mjs" import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default { resolveLoader: { alias: { 'worker-loader': require.resolve('worker-rspack-loader'), }, }, };


  </Tab>
  <Tab label="CJS">

```js title="rspack.config.cjs"
module.exports = {
  resolveLoader: {
    alias: {
      'worker-loader': require.resolve('worker-rspack-loader'),
    },
  },
};

</Tab> </Tabs>