#Web Workers

This guide explains how to configure and use Web Workers in Rslib projects.

#Use the worker constructor

#Basic usage

You can create a Worker with the standard constructor syntax:

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

Rslib rewrites the Worker URL to reference the generated JavaScript file and emits the Worker as an ES module:

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

More Worker syntax can be found in Rspack - Web Workers.

#Limitations

Rslib relies on static analysis to process new Worker and similar Worker APIs, so you must pass new URL('./worker.ts', import.meta.url) directly. URL strings and URL objects passed through variables are not supported:

new Worker('./worker.ts');

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

#Output modes

The lib.bundle option determines how Workers are built. The following example uses the same source files to show the output generated in bundle and bundleless modes:

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

import { add } from './helper';

self.onmessage = ({ data }: MessageEvent<[number, number]>) => {
  self.postMessage(add(data[0], data[1]));
};

export const add = (left: number, right: number) => left + right;

#Bundle mode

In bundle mode, Rslib emits the Worker entry as a separate chunk and bundles modules imported by the Worker into that chunk:

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

const add = (left, right) => left + right;
self.onmessage = ({ data }) => {
  self.postMessage(add(data[0], data[1]));
};
export {};

#Bundleless mode

In bundleless mode, Rslib preserves the source module structure and rewrites Worker URLs and imports inside Workers to reference the corresponding ESM output files:

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

import { add } from './helper.js';
self.onmessage = ({ data }) => {
  self.postMessage(add(data[0], data[1]));
};

const add = (left, right) => left + right;
export { add };

#Import with query suffixes

Rslib supports importing Web Workers with query suffixes in bundle mode; for details, see Rsbuild - Web Workers.

#Emit a separate worker file

You can append ?worker to an import request to import a Web Worker script, which Rslib emits as a separate ESM file:

import MyWorker from './worker.ts?worker';

export const worker = new MyWorker();

#Inline a worker

You can append ?worker&inline to an import request to import a Web Worker script, which Rslib inlines into the JavaScript file that imports the Worker instead of emitting a separate Worker file:

import InlineWorker from './worker.ts?worker&inline';

export const worker = new InlineWorker();

#Type declarations

When you import a Worker with a query suffix in TypeScript code, TypeScript may report that the module is missing type definitions:

TS2307: Cannot find module './worker.ts?worker' or its corresponding type declarations.

In this case, you can add the preset types provided by @rslib/core to tsconfig.json:

{
  "compilerOptions": {
    "types": ["@rslib/core/types"]
  }
}

The preset types include declarations for *?worker, *?worker&inline, and *?inline&worker.