Reference

Dedicated Worker API

Compressed browser surface for one-owner workers. Normative details: WHATWG Web workers.

Construct (main thread)

// Classic script (default)
const worker = new Worker("worker.js");

// Module worker (import / strict / clean scope)
const mod = new Worker("worker.mjs", { type: "module" });

// Bundler-friendly URL (Vite / webpack guidance via MDN)
const w = new Worker(new URL("./worker.js", import.meta.url));

// Optional debug name → DedicatedWorkerGlobalScope.name
const named = new Worker("worker.js", { name: "csv-parser" });

• Script URL must be loadable under normal worker rules (same-origin classic case; cross-origin fails via error event in modern browsers — see MDN).
• Blob URLs work for inlined worker source.
• Spec guidance: workers are relatively heavy; prefer long-lived instances over one worker per tiny task.

Main-thread surface (Worker)

worker.postMessage(data);
// optional transfer list (later lessons): worker.postMessage(buf, [buf]);

worker.onmessage = (e) => {
  // e.data — structured-clone copy from the worker
};

worker.onerror = (e) => {
  // e.message, e.filename, e.lineno
};

worker.onmessageerror = (e) => {
  // deserialization of an incoming message failed
};

worker.terminate(); // immediate kill; in-flight work dies

Inside the worker

// Global is DedicatedWorkerGlobalScope (self)
// No DOM. No window. self is the worker global.

onmessage = (e) => {
  const input = e.data;
  // … heavy work …
  postMessage(result); // back to the owner
};

// Graceful self-shutdown (discards queued tasks)
close();

// Classic workers only:
importScripts("lib-a.js", "lib-b.js"); // sync load + run

• Main thread: hang postMessage / onmessage on the Worker object.
• Worker: postMessage / onmessage are on the global scope (the worker is the global).

Shutdown: terminate vs close

SPA hygiene (design default)

// mount
const worker = new Worker(new URL("./job.js", import.meta.url));
worker.onmessage = handleResult;
worker.onerror = handleError;

// unmount / leave route
worker.terminate();
// drop references so GC can reclaim the Worker object

Message shape (design habit)

// Correlate request/response yourself — the API is fire-and-forget events
worker.postMessage({ id: "req-17", type: "parse", payload: text });

worker.onmessage = (e) => {
  const { id, type, result, error } = e.data;
  // match id to the pending promise / UI job
};