Web Workers skill for Claude Code

A worker is worth it when the main thread is blocked by computation that does not need the DOM. Done well means: the long task was found in a recording, the work moved (or was split) so no main-thread task from it exceeds 50 ms, the cost of sending data to the worker was measured and is smaller than the work saved, and INP or the frame timeline proves the improvement.

Ground rules

• Profile first. If the long task is rendering, layout, or framework re-renders, a worker will not help — fix that work (see react-rerenders or core-web-vitals).
• Try the cheaper fixes in order: do less work, cache it, split it with yielding, then move it to a worker.
• Message passing is not free: structured clone runs synchronously on the sender and the receiver. Send small messages, transfer buffers, and keep large data inside the worker.
• One worker that owns its data beats a worker you ship the whole dataset to per call.
• Every worker call can fail or be superseded: handle errors, cancel stale requests, terminate runaway work.

Workflow

- [ ] 1. Record the slow interaction; identify the long task and its call stack
- [ ] 2. Classify the work: DOM/render (not a worker job) or pure computation
- [ ] 3. Choose: yield, Web Worker, SharedWorker, worklet, OffscreenCanvas, WebAssembly
- [ ] 4. Measure message cost with a real payload (scripts/message_cost.mjs)
- [ ] 5. Design the worker API: worker owns data, small requests, transfer buffers
- [ ] 6. Wire the bundler (new Worker(new URL(...), { type: "module" }))
- [ ] 7. Add cancellation, errors, lifecycle (create lazily, terminate when done)
- [ ] 8. Re-record: no long task from this work; INP or frame times improved

1. Find the long task

• Chrome DevTools Performance panel, CPU 4× slowdown, record the interaction. Long tasks (over 50 ms) have a red corner on the Main track. Open Bottom-Up for the self time.
• Field and lab attribution: Long Animation Frames (PerformanceObserver with type: "long-animation-frame", Chromium 123+) gives blockingDuration and per-script attribution; the web-vitals attribution build links slow INP interactions to them.
• INP is good at ≤ 200 ms (p75). If the interaction’s processing time is dominated by your own computation, it is a worker or yielding candidate.

new PerformanceObserver((list) => {
  for (const e of list.getEntries()) {
    if (e.blockingDuration > 0) console.log(e.duration, e.blockingDuration, e.scripts.map((s) => s.sourceURL));
  }
}).observe({ type: "long-animation-frame", buffered: true });

3. Choose the mechanism

Work	Use	Why
A loop over many small items where the result is DOM updates	Yield inside the loop (scheduler.yield(), fallback setTimeout(0))	Work needs the DOM; yielding lets input run between chunks
Pure computation over 50 ms: parse CSV/JSON, search index, diff, sort/aggregate large data, markdown or syntax highlighting, hashing, image filters	Dedicated Worker	Runs in parallel; the main thread stays responsive
One connection or cache shared by several tabs of the same origin	SharedWorker	One instance per origin; check support — Chrome for Android only recently added it
Real-time audio processing	AudioWorklet	Runs on the audio rendering thread with tight timing
Canvas or WebGL rendering that janks the page	OffscreenCanvas in a worker	Rendering moves with the computation
Numeric hot loops that are still too slow in a worker	WebAssembly inside the worker	Faster compute; keep it off the main thread too
Network caching, offline, push	Service worker (pwa-service-workers skill)	Not a compute thread; the browser may stop it any time

scheduler.yield() ships in Chromium 129+ and Firefox 142+, not in Safari; feature-detect:

const yieldToMain = () =>
  globalThis.scheduler?.yield ? scheduler.yield() : new Promise((r) => setTimeout(r, 0));

4. Measure the message cost

Run the bundled script with a sample of the real message:

node scripts/message_cost.mjs --json sample-payload.json --budget-ms 8
node scripts/message_cost.mjs --objects 50000          # synthetic records
node scripts/message_cost.mjs --bytes 50000000         # ArrayBuffer: copy vs transfer

It reports structured-clone time, postMessage round trip with copy and with transfer, and exits 1 when the one-way copy exceeds the budget. Node’s serializer approximates Chromium; confirm in the browser recording (the “Serialize”/“Deserialize” work appears around postMessage).

What crosses the boundary:

Kind	Behavior
Plain objects, arrays, Map, Set, Date, RegExp, Blob, File, typed arrays	Structured clone (copied)
ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas, streams, VideoFrame	Transferable: moved at near-zero cost when listed in the transfer list
Functions, DOM nodes, class methods/prototypes	Not cloneable: DataCloneError, or class instances arrive as plain objects
SharedArrayBuffer	Shared memory; requires cross-origin isolation (Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp or credentialless); check crossOriginIsolated

// transfer the buffer, not the typed array
worker.postMessage({ pixels }, [pixels.buffer]);   // pixels.byteLength is 0 afterwards

If the message is too big: send ids or deltas, load the data inside the worker (it has fetch and IndexedDB), use columnar typed arrays instead of arrays of objects, or keep results in the worker and request only the visible slice.

5. Worker API with Comlink

// search.worker.ts
import * as Comlink from "comlink";
import { buildIndex, query } from "./search-core";   // pure functions, unit-testable

let index: ReturnType<typeof buildIndex> | null = null;

const api = {
  async load(url: string) { const docs = await (await fetch(url)).json(); index = buildIndex(docs); return docs.length; },
  search(q: string, limit = 50) { return index ? query(index, q, limit) : []; },   // returns a small slice
};
export type SearchApi = typeof api;
Comlink.expose(api);

// search-client.ts
import * as Comlink from "comlink";
import type { SearchApi } from "./search.worker";

let api: Comlink.Remote<SearchApi> | null = null;
export function searchWorker() {
  api ??= Comlink.wrap<SearchApi>(new Worker(new URL("./search.worker.ts", import.meta.url), { type: "module" }));
  return api;
}

// stale-result guard: only the latest query wins
let latest = 0;
export async function search(q: string) {
  const id = ++latest;
  const hits = await searchWorker().search(q);
  return id === latest ? hits : null;
}

• Every Comlink call is async. Callbacks must be wrapped in Comlink.proxy(fn); call proxy[Comlink.releaseProxy]() when done or they leak. Use Comlink.transfer(value, [buffer]) to move buffers.
• Without Comlink, use { id, type, payload } messages and a Map<id, {resolve, reject}> on the client; same rules.
• Cancellation: a stale-id guard drops results; for long CPU loops, check a cancel flag between chunks (send a “cancel” message, or poll a SharedArrayBuffer flag), or worker.terminate() and recreate.
• Pools: only for many independent jobs (image batch). Size to Math.max(1, (navigator.hardwareConcurrency ?? 4) - 1), capped (4 is a sensible cap on mobile), and queue the rest.

6. Bundler setup

const worker = new Worker(new URL("./parse.worker.ts", import.meta.url), { type: "module" });

• Vite and webpack 5 both detect this exact form. Write new URL(...) inline inside new Worker(...) — assigning the URL to a variable first defeats detection (Vite then treats it as a plain asset; webpack does not support it). Options must be static literals.
• Vite alternatives: import ParseWorker from "./parse.worker?worker" (default export is a constructor), ?worker&inline (base64-inlined), ?worker&url, ?sharedworker.
• webpack 5 needs no worker-loader; name the chunk with /* webpackChunkName: "parse-worker" */ before new URL.
• TypeScript: add /// <reference lib="webworker" /> at the top of worker files (or a separate tsconfig with "lib": ["ES2022", "WebWorker"]) so self is typed correctly.
• SSR frameworks: create workers only in client code (inside an effect or event handler), never at module scope of code that runs on the server.
• CSP: allow the worker script origin with worker-src (falls back to script-src).

OffscreenCanvas

const offscreen = canvas.transferControlToOffscreen();
worker.postMessage({ canvas: offscreen }, [offscreen]);
// in the worker: const ctx = e.data.canvas.getContext("2d"); requestAnimationFrame(draw);

Baseline widely available. Input events still arrive on the main thread: forward pointer coordinates and resize sizes to the worker as small messages.

Gotchas

• Worker startup (script download, parse, init) costs time; create the worker before it is needed (on idle or when the feature mounts), not on the first click.
• Workers have no window, document, or localStorage; they do have fetch, IndexedDB, crypto.subtle, WebSockets, and timers.
• Posting one message per item in a loop floods the main thread with message events. Batch results and apply them once per frame.
• Transferring detaches the sender’s buffer; code that reads it afterwards gets length 0.
• The worker holds its own copy of data: moving a 200 MB dataset doubles memory unless the main thread drops its copy.
• Errors inside the worker do not reject your promise unless you wire error and messageerror listeners (Comlink rethrows errors thrown inside exposed methods).
• Unit tests in jsdom have no Worker. Keep the logic in pure modules tested directly; keep the worker file a thin adapter; cover the wiring with an e2e test.

Verification

1. Re-record the same interaction at 4× CPU: no main-thread task over 50 ms from the moved work; the work appears on a worker track.
2. scripts/message_cost.mjs with the real payload is within budget, and the recording shows serialization well below the work saved.
3. INP for the interaction (web-vitals attribution or the Performance panel’s interactions track) dropped; in the field, compare p75 before and after release.
4. Typing or scrolling while the worker computes stays smooth; superseded requests do not overwrite newer results.
5. Kill the worker (throw inside it): the UI shows an error state and recovers.

If the task did not shrink, the expensive part was not the code you moved: return to step 1 with the new recording.

Report template

**Interaction:** typing in product search (INP p75 420 ms, lab long task 310 ms)
**Cause:** client-side filtering of 60k products on every keystroke (search-core.ts)
**Change:** index built and queried in a module worker via Comlink; worker owns data,
returns top 50 ids; stale-query guard
**Message cost:** 0.4 ms per query (message_cost.mjs, real payload)
**Result:** no long tasks during typing; lab INP 90 ms; field p75 to be confirmed after 28 days