Web Workers

Sentry's Browser SDK supports the Web Workers API. You can use the SDK in different ways, though we recommend initializing it in the main thread to capture unhandled errors from workers automatically.

Recommended Setup

Available since : 9.40.0

To capture unhandled errors from Web Workers, initialize Sentry in your application code that runs on the main thread and let the SDK know about the web worker:

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
});

const worker = new Worker("worker.js");

// Add the integration before listening to worker messages
Sentry.addIntegration(Sentry.webWorkerIntegration({ worker }));

worker.onmessage = (event) => {
  // ...
};

Then, establish communication between the worker and the SDK:

import * as Sentry from "@sentry/browser";

// Call this before posting any message
Sentry.registerWorker({ self });

// Errors from `onmessage` callback of `worker.js`
// will be captured automatically.
self.postMessage("Worker ready!");
self.onmessage = (event) => {
  // ...
};

Multiple Workers

The sentryWebWorkerIntegration supports registering multiple workers. You can add them directly, when you initialize the integration, or later on. This is helpful, if you have workers that are initialized at different points in time in your application lifecycle.

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
});

const worker1 = new Worker("worker.js");
const worker2 = new Worker("worker2.js");

// Multiple workers can be added directly:
const webWorkerIntegration = Sentry.webWorkerIntegration({
  worker: [worker1, worker2],
});
Sentry.addIntegration(webWorkerIntegration);

// or later on:
const worker3 = new Worker("worker3.js");
webWorkerIntegration.addWorker(worker3);

Manually Capturing Errors

To capture errors or messages manually, via Sentry.captureMessage or Sentry.captureException inside Web Workers, you can also import the SDK in the worker and initialize it.

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
});

self.onmessage = (message) => {
  // This message will be captured
  Sentry.captureMessage("Message received");

  // This error will also be captured.
  throw new Error();
};

Note that initializing the SDK in the worker completely decouples it from the SDK running on the main thread. This means that data like user, tags, traces or scope data set on either side will not be shared with the other side.

Sometimes, this is the better approach, for instance if you develop a worker that is used in arbitrary applications. Other times, if the worker is just part of your application, you likely want to use the SDK from the main thread.

Integrations

Note, that if you use non-default integrations inside web workers, they may not function as expected. However, non-default integrations that are enabled on the main thread SDK, won't be affected and will work as expected. This includes Session Replay.

Source Maps

To ensure that errors from web workers are properly mapped to their original source code, you need to provide source maps to Sentry. You likely already provide source maps to Sentry for your main application code, but you might need to make adjustments for your worker.

Importantly, ensure that your bundler also emits source maps for the worker bundle(s).

Vite

If you use Vite to build your worker, note that the worker build does not take the same plugin as the main code build. Therefore, you need to add Sentry's Vite plugin to the worker build, in addition to the top-level plugins array:

const sentryPlugin = sentryVitePlugin({
  org: "sentry-sdks",
  project: "javascript",
});

export default defineConfig({
  build: {
    // This enables source maps for main and worker bundles
    sourcemap: "hidden",
  },

  // Vite plugin for main bundle
  plugins: [sentryPlugin],

  worker: {
    // Vite plugin for worker bundle
    plugins: () => [...sentryPlugin],
  },
});