Web Workers and Worklets for Off-Main-Thread Work

Concurrency primitives for keeping the main thread responsive. Workers provide general-purpose parallelism via message passing; worklets integrate directly into the browser’s rendering pipeline for synchronized paint, animation, and audio processing.

Abstract

The browser’s main thread handles JavaScript execution, DOM updates, style calculation, layout, paint, and compositing in a single event loop. Long-running JavaScript blocks this entire pipeline, causing dropped frames and unresponsive UI.

Workers solve this by running JavaScript in separate threads with isolated memory. Communication happens through postMessage() and the Structured Clone Algorithm—data is copied by default, or ownership can be transferred for zero-copy performance. Three worker types serve different purposes: Dedicated Workers for compute-heavy tasks, Shared Workers for cross-tab coordination, and Service Workers for network interception and offline support.

Worklets address a different problem: integrating custom code into the rendering pipeline itself. Paint Worklets generate custom CSS images during the paint phase. Animation Worklets produce frames off-thread while staying synchronized with compositing. Audio Worklets process samples on the audio rendering thread with sub-millisecond timing requirements. Worklets sacrifice API flexibility (no DOM, limited globals) for guaranteed synchronization with their pipeline stage.

SharedArrayBuffer enables true shared memory when cross-origin isolation is configured, allowing lock-free algorithms via Atomics—but the security requirements and complexity make it suitable only for specific high-performance scenarios.

Worker Types and Lifecycle

Dedicated Workers

A Dedicated Worker creates a one-to-one relationship between a script and a worker thread. The worker has its own global scope (DedicatedWorkerGlobalScope), event loop, and JavaScript heap.

2 collapsed lines
1
// main.js
2
// Dedicated workers are bound to their creator
3

4
const worker = new Worker("/compute-worker.js", {
5
  type: "module", // Enable ES modules (default: 'classic')
6
  name: "compute", // Optional name for debugging
7
})
8

9
worker.postMessage({ task: "factorial", n: 1000000n })
6 collapsed lines
10

11
// compute-worker.js
12
self.onmessage = (e) => {
13
  const result = computeFactorial(e.data.n)
14
  self.postMessage(result)
15
}

Lifecycle states (per WHATWG HTML spec):

Termination occurs when terminate() is called or the worker becomes impermissible. Calling terminate() immediately sets the closing flag, discards queued tasks, and aborts running scripts—there is no graceful shutdown.

Shared Workers

Shared Workers implement many-to-one communication: multiple browsing contexts within the same origin connect to a single worker instance.

2 collapsed lines
1
// main.js (in multiple tabs)
2
// Multiple tabs connect to the same named worker
3

4
const worker = new SharedWorker("/shared-state.js", "session-state")
5
worker.port.start()
6
worker.port.postMessage({ action: "subscribe", channel: "updates" })
7
worker.port.onmessage = (e) => {
8
  console.log("Update:", e.data)
9
}
10

10 collapsed lines
11
// shared-state.js
12
const connections = new Set()
13

14
self.onconnect = (e) => {
15
  const port = e.ports[0]
16
  connections.add(port)
17
  port.onmessage = (msg) => {
18
    // Broadcast to all connected ports
19
    for (const p of connections) p.postMessage(msg.data)
20
  }
21
}

Key differences from Dedicated Workers:

• Communication uses explicit MessagePort (accessed via worker.port)
• The worker survives as long as at least one port remains connected
• onconnect fires each time a new context connects
• State persists across page navigations within the same origin

Shared Workers remain alive during the “between-loads shared worker timeout” when a page navigates—allowing reconnection without losing state.

Service Workers

Service Workers operate under browser control rather than page control. The browser starts them for network events and terminates them when idle.

3 collapsed lines
1
// main.js
2
// Service workers are registered, not constructed
3
// They control pages matching their scope
4

5
if ("serviceWorker" in navigator) {
6
  const reg = await navigator.serviceWorker.register("/sw.js", {
7
    scope: "/",
8
    type: "module",
9
  })
10
}
11

8 collapsed lines
12
// sw.js
13
self.addEventListener("install", (e) => {
14
  e.waitUntil(caches.open("v1").then((c) => c.addAll(["/app.js", "/styles.css"])))
15
})
16

17
self.addEventListener("fetch", (e) => {
18
  e.respondWith(caches.match(e.request).then((r) => r || fetch(e.request)))
19
})

Critical behavioral differences:

Service Workers must complete event handlers quickly. Long-running operations should use event.waitUntil() to extend the worker’s lifetime, but the browser may still terminate after a timeout (typically 30 seconds to 5 minutes depending on the event type).

Module Workers vs Classic Workers

The type option determines script loading semantics:

Classic Workers (default):

• importScripts() synchronously loads and executes scripts
• No import/export statements (throws SyntaxError)
• No strict mode by default
• Top-level this refers to the global scope

Module Workers (type: 'module'):

• Standard ES module semantics with import/export
• importScripts() always throws TypeError
• Strict mode enabled, cannot be disabled
• Top-level this is undefined
• Supports import.meta.url for script location
• Enables <link rel="modulepreload"> for preloading

2 collapsed lines
1
// worker.js (type: 'module')
2
// Dynamic imports work in module workers
3

4
import { heavyCompute } from "./compute.js"
5

6
self.onmessage = async (e) => {
7
  // Dynamic import for code splitting
8
  const { processImage } = await import("./image-processor.js")
3 collapsed lines
9
  const result = await processImage(e.data)
10
  self.postMessage(result)
11
}

Module workers have slightly higher initialization overhead due to module resolution, but provide better code organization and tree-shaking opportunities.

Communication and Data Transfer

Structured Clone Algorithm

postMessage() serializes data using the Structured Clone Algorithm, which recursively copies objects while tracking references to handle cycles:

Supported types:

• Primitives (except Symbol)
• Object, Array, Map, Set
• Date, RegExp
• ArrayBuffer, TypedArray, DataView
• Blob, File, FileList
• ImageData, ImageBitmap
• Error objects (limited properties)

Cannot be cloned:

• Functions (throws DataCloneError)
• DOM nodes
• Property descriptors, getters/setters
• Prototype chain (only own enumerable properties)
• Symbols

3 collapsed lines
1
// Cycles are preserved
2
const obj = { name: "circular" }
3
obj.self = obj
4
worker.postMessage(obj) // Works—cycle is maintained
5

6
// Functions fail
7
worker.postMessage({ fn: () => {} }) // DataCloneError
8

9
// Class instances lose their prototype
10
class Point {
11
  constructor(x, y) {
12
    this.x = x
13
    this.y = y
14
  }
6 collapsed lines
15
}
16
worker.postMessage(new Point(1, 2))
17
// Worker receives: { x: 1, y: 2 } (plain object, no Point prototype)
18

19
// Maps and Sets are preserved
20
worker.postMessage(new Map([["key", "value"]]))
21
// Worker receives: Map { 'key' => 'value' }

Transferable Objects

Transferables move ownership rather than copying—the source context loses access, but transfer is nearly instantaneous regardless of size.

Transferable types:

• ArrayBuffer
• MessagePort
• ImageBitmap
• OffscreenCanvas
• ReadableStream, WritableStream, TransformStream

2 collapsed lines
1
// Create a 100MB buffer
2
const buffer = new ArrayBuffer(100 * 1024 * 1024)
3

4
console.log(buffer.byteLength) // 104857600
5

6
// Transfer ownership to worker
7
worker.postMessage(buffer, [buffer])
8

9
console.log(buffer.byteLength) // 0 (detached)
10

11
// Worker receives the buffer instantly
6 collapsed lines
12
// In worker:
13
self.onmessage = (e) => {
14
  const received = e.data
15
  console.log(received.byteLength) // 104857600
16
  // Worker now owns this buffer
17
}

Performance Characteristics

Cloning overhead scales with data complexity:

For high-frequency communication (e.g., 60 Hz animation data), even small cloning overhead accumulates. Transfer 64-byte typed arrays if sending them 60 times per second.

Error Handling

Worker errors propagate via the error event:

3 collapsed lines
1
// Main thread
2
worker.onerror = (event) => {
3
  // ErrorEvent properties:
4
  console.error(`${event.filename}:${event.lineno}:${event.colno}`)
5
  console.error(event.message)
6
  event.preventDefault() // Suppress default console error
7
}
8

9
worker.onmessageerror = (event) => {
10
  // Fires when deserialization fails
11
  console.error("Failed to deserialize message")
12
}
13

5 collapsed lines
14
// Worker can catch its own errors
15
self.onerror = (message, filename, lineno, colno, error) => {
16
  // Return true to prevent propagation to main thread
17
  return true
18
}

Unhandled promise rejections in workers generate unhandledrejection events on the worker global scope, similar to main thread behavior.

SharedArrayBuffer and Atomics

SharedArrayBuffer enables true concurrent memory access between contexts—but requires cross-origin isolation due to Spectre mitigation requirements.

Cross-Origin Isolation Requirements

Two HTTP headers must be present:

1
Cross-Origin-Opener-Policy: same-origin
2
Cross-Origin-Embedder-Policy: require-corp

COOP: same-origin breaks the relationship between your page and cross-origin popups (they can’t access each other’s windows). COEP: require-corp requires all cross-origin resources to explicitly opt in via Cross-Origin-Resource-Policy headers.

3 collapsed lines
1
// Runtime check before using SharedArrayBuffer
2
if (!crossOriginIsolated) {
3
  throw new Error("SharedArrayBuffer requires cross-origin isolation")
4
}
5

6
const sab = new SharedArrayBuffer(1024)
7
const view = new Int32Array(sab)

The credentialless variant of COEP relaxes requirements by allowing cross-origin resources without CORP headers but stripping their cookies and credentials:

1
Cross-Origin-Embedder-Policy: credentialless

Atomics Operations

Atomics provide synchronization primitives for concurrent access:

5 collapsed lines
1
// Shared buffer layout:
2
// [0]: ready flag (0 = not ready, 1 = data available)
3
// [1-n]: data
4

5
const sab = new SharedArrayBuffer(1024)
6
const control = new Int32Array(sab, 0, 1)
7
const data = new Float64Array(sab, 8)
8

9
// In producer worker:
10
function produce(value) {
11
  data[0] = value
12
  Atomics.store(control, 0, 1) // Mark ready
13
  Atomics.notify(control, 0, 1) // Wake one waiter
14
}
15

16
// In consumer worker:
17
function consume() {
18
  while (Atomics.load(control, 0) === 0) {
19
    Atomics.wait(control, 0, 0) // Block until notified
20
  }
21
  const value = data[0]
22
  Atomics.store(control, 0, 0) // Mark consumed
23
  return value
24
}
11 collapsed lines
25

26
// Available atomic operations:
27
// Atomics.load(ta, index) - atomic read
28
// Atomics.store(ta, index, value) - atomic write
29
// Atomics.add(ta, index, value) - atomic add, returns old value
30
// Atomics.sub(ta, index, value) - atomic subtract
31
// Atomics.and/or/xor(ta, index, value) - bitwise operations
32
// Atomics.compareExchange(ta, index, expected, replacement)
33
// Atomics.exchange(ta, index, value) - atomic swap
34
// Atomics.wait(ta, index, value, timeout?) - block until changed
35
// Atomics.notify(ta, index, count?) - wake waiting threads

Critical constraint: Atomics.wait() blocks the calling thread. On the main thread, this blocks rendering entirely. Never use Atomics.wait() on the main thread—use Atomics.waitAsync() (returns a Promise) instead.

Design Rationale: Why Cross-Origin Isolation?

SharedArrayBuffer enables high-resolution timing attacks (Spectre-style):

2 collapsed lines
1
// Attacker spins in a worker, incrementing a counter
2
// Main thread reads the counter before/after a memory access
3
// The delta reveals cache timing, potentially leaking memory contents
4

5
const sab = new SharedArrayBuffer(4)
6
const counter = new Int32Array(sab)
7

5 collapsed lines
8
// Worker thread (spinning)
9
while (true) Atomics.add(counter, 0, 1)
10

11
// Main thread measures timing
12
const start = Atomics.load(counter, 0)
13
// ... memory access ...
14
const elapsed = Atomics.load(counter, 0) - start

Cross-origin isolation contains this threat by:

1. Preventing cross-origin iframes from accessing your browsing context
2. Ensuring no cross-origin window can observe timing side channels
3. Limiting potential information leakage to same-origin resources

Worklets: Rendering Pipeline Integration

Worklets differ fundamentally from workers: they execute synchronously within specific rendering pipeline stages rather than as independent concurrent threads.

Why Worklets Exist

Workers cannot solve synchronous rendering needs:

4 collapsed lines
1
// Problem: Worker results arrive too late
2
worker.postMessage({ width: 100, height: 100 })
3
worker.onmessage = (e) => {
4
  // This runs AFTER the current frame has painted
5
  element.style.backgroundImage = `url(${e.data})`
6
  // User sees a frame with the OLD background
7
}

Worklets execute during the rendering phase itself:

1
/* Paint worklet runs during paint phase */
2
.custom-bg {
3
  background: paint(custom-gradient);
4
}
5
/* Browser calls paint() synchronously before compositing */

Worklet Restrictions

To enable synchronous pipeline integration, worklets sacrifice flexibility:

The browser can create multiple worklet global scopes and instantiate your class multiple times. Never rely on instance state persisting across invocations.

Paint Worklet (CSS Painting API)

Paint Worklets generate custom CSS <image> values during the paint phase.

4 collapsed lines
1
// paint-checkerboard.js
2
// Paint worklets define custom CSS image generators
3

4
class CheckerboardPainter {
5
  static get inputProperties() {
6
    return ["--checker-size", "--checker-color-1", "--checker-color-2"]
7
  }
8

9
  paint(ctx, geom, props) {
10
    const size = parseInt(props.get("--checker-size")) || 32
11
    const color1 = props.get("--checker-color-1").toString() || "#fff"
12
    const color2 = props.get("--checker-color-2").toString() || "#000"
13

14
    for (let y = 0; y < geom.height; y += size) {
15
      for (let x = 0; x < geom.width; x += size) {
16
        const isEven = (x / size + y / size) % 2 === 0
17
        ctx.fillStyle = isEven ? color1 : color2
18
        ctx.fillRect(x, y, size, size)
19
      }
20
    }
21
  }
22
}
23

24
registerPaint("checkerboard", CheckerboardPainter)
3 collapsed lines
25

26
// main.js - register the worklet
27
CSS.paintWorklet.addModule("/paint-checkerboard.js")

2 collapsed lines
1
/* CSS usage */
2
.checkerboard {
3
  --checker-size: 20;
4
  --checker-color-1: #f0f0f0;
5
  --checker-color-2: #333;
6
  background: paint(checkerboard);
7
}

PaintRenderingContext2D is a subset of CanvasRenderingContext2D:

• Supported: fillRect, strokeRect, drawImage, arc, bezierCurveTo, path operations, transforms
• Not supported: Text rendering (fillText, strokeText), getImageData, putImageData

Browser behavior:

• Browser may cache results when size, styles, and arguments are unchanged
• Elements outside the viewport may defer painting
• Long-running paint() calls may be terminated

Support (as of 2025): Chrome/Edge (full), Safari (partial), Firefox (in development).

Animation Worklet

Animation Worklets produce animation frames off-thread, synchronized with compositing.

4 collapsed lines
1
// parallax-animator.js
2
// Animation worklet for scroll-driven effects
3

4
class ParallaxAnimator {
5
  constructor(options) {
6
    this.rate = options.rate || 0.5
7
  }
8

9
  animate(currentTime, effect) {
10
    // currentTime comes from the timeline (e.g., scroll position)
11
    // effect.localTime controls the animation progress
12
    effect.localTime = currentTime * this.rate
13
  }
14
}
15

16
registerAnimator("parallax", ParallaxAnimator)
17

18
// main.js
19
await CSS.animationWorklet.addModule("/parallax-animator.js")
11 collapsed lines
20

21
const scroller = document.querySelector(".scroll-container")
22
const target = document.querySelector(".parallax-element")
23

24
const animation = new WorkletAnimation(
25
  "parallax",
26
  new KeyframeEffect(target, [{ transform: "translateY(0)" }, { transform: "translateY(-200px)" }], {
27
    duration: 1,
28
    fill: "both",
29
  }),
30
  new ScrollTimeline({ source: scroller }),
31
  { rate: 0.3 },
32
)
33
animation.play()

Key differences from Web Animations:

• Animator instances directly control effect.localTime rather than inheriting from timeline
• Execution may occur on a separate thread (compositor thread)
• Main thread jank does not affect animation smoothness
• ScrollTimeline integration enables scroll-linked effects without scroll event handlers

Support (as of 2025): Chrome/Edge (full), Safari/Firefox (not yet implemented).

Audio Worklet

Audio Worklets process audio samples on the Web Audio rendering thread with strict real-time constraints.

4 collapsed lines
1
// gain-processor.js
2
// Audio worklet for custom sample processing
3

4
class GainProcessor extends AudioWorkletProcessor {
5
  static get parameterDescriptors() {
6
    return [
7
      {
8
        name: "gain",
9
        defaultValue: 1.0,
10
        minValue: 0,
11
        maxValue: 2,
12
        automationRate: "a-rate", // per-sample automation
13
      },
14
    ]
15
  }
16

17
  process(inputs, outputs, parameters) {
18
    const input = inputs[0]
19
    const output = outputs[0]
20
    const gain = parameters.gain
21

22
    for (let channel = 0; channel < output.length; channel++) {
23
      for (let i = 0; i < output[channel].length; i++) {
24
        // gain may be k-rate (single value) or a-rate (per-sample)
16 collapsed lines
25
        const g = gain.length > 1 ? gain[i] : gain[0]
26
        output[channel][i] = input[channel]?.[i] * g || 0
27
      }
28
    }
29
    return true // Continue processing
30
  }
31
}
32

33
registerProcessor("gain-processor", GainProcessor)
34

35
// main.js
36
const ctx = new AudioContext()
37
await ctx.audioWorklet.addModule("/gain-processor.js")
38

39
const gainNode = new AudioWorkletNode(ctx, "gain-processor")
40
gainNode.parameters.get("gain").value = 0.5
41

42
source.connect(gainNode)
43
gainNode.connect(ctx.destination)

Render quantum: Fixed at 128 samples. At 48 kHz sample rate, this is ~2.67ms per callback. Your process() must complete within this time or audio glitches occur.

Communication: Use MessagePort (accessed via node.port / this.port) for control messages. Never allocate memory or perform I/O in process().

Support (as of 2025): All modern browsers (mature API).

Layout Worklet (Experimental)

Layout Worklets enable custom CSS layout algorithms. The API is under development and not production-ready.

3 collapsed lines
1
// Experimental - API may change
2
// Available in Chrome behind experimental flag
3

4
class MasonryLayout {
5
  static get inputProperties() {
6
    return ["--columns"]
7
  }
8

9
  async intrinsicSizes(children, edges, styleMap) {
10
    // Return intrinsic sizing
11
  }
12

13
  async layout(children, edges, constraints, styleMap) {
14
    // Position children, return fragment
15
  }
16
}
17

18
registerLayout("masonry", MasonryLayout)

Status (as of 2025): Hidden behind flags in Chromium. Specification still evolving. Not recommended for production.

Use-Case Decision Matrix

Debugging and Profiling

Chrome DevTools

Workers:

• Sources panel → Threads sidebar shows all workers
• Console can target specific worker contexts
• Performance panel includes worker activity in flame chart
• Memory panel can snapshot worker heaps

Worklets:

• Paint worklets: Use “Rendering” drawer → “Paint flashing” to see repaints
• Audio worklets: chrome://webaudio-internals shows audio graph
• Performance panel shows worklet execution in appropriate tracks

Common Issues

Worker not starting:

• Check console for script fetch errors (404, CORS)
• Module workers require correct MIME type (text/javascript)
• Mixed content blocks HTTP workers on HTTPS pages

Messages not received:

• Verify port.start() called for SharedWorker ports
• Check for DataCloneError in console (non-clonable data)
• Confirm worker hasn’t terminated (worker.terminate() is immediate)

SharedArrayBuffer unavailable:

• Verify crossOriginIsolated === true in console
• Check response headers for COOP/COEP
• Ensure all cross-origin resources have CORP headers

Conclusion

Workers and worklets serve distinct concurrency needs. Workers provide general-purpose parallelism with message-passing isolation—safe by default, with SharedArrayBuffer available when true shared memory is required. Worklets integrate into the rendering pipeline for use cases where asynchronous communication cannot meet timing requirements.

Choose workers for compute offloading and background tasks. Choose worklets when you need synchronization with paint, animation, or audio rendering phases. For most applications, Dedicated Workers with Transferables provide the best balance of simplicity and performance.

Appendix

Prerequisites

• JavaScript event loop and asynchronous execution model
• Basic understanding of browser rendering pipeline (style → layout → paint → composite)
• Familiarity with Promises and async/await
• For SharedArrayBuffer: Understanding of concurrent programming concepts

Terminology

• Structured Clone Algorithm: The serialization mechanism used by postMessage() to copy JavaScript values between contexts
• Transferable: An object type whose ownership can be moved (not copied) between contexts via postMessage()
• Render Quantum: The fixed block size (128 samples) processed per Audio Worklet callback
• Cross-Origin Isolation: A security mode requiring COOP and COEP headers that enables SharedArrayBuffer

Summary

• Dedicated Workers create 1:1 thread relationships with explicit terminate() control
• Shared Workers serve multiple tabs with port-based communication and shared state
• Service Workers run under browser control for network interception and offline support
• Module workers (type: 'module') enable ES module syntax; classic workers use importScripts()
• Structured cloning copies data; transferables move ownership for zero-copy performance
• SharedArrayBuffer requires cross-origin isolation (COOP + COEP headers) due to Spectre mitigations
• Paint Worklets generate custom CSS images synchronously during paint
• Animation Worklets produce frames off-thread, integrated with scroll timelines
• Audio Worklets process samples in 128-sample blocks with < 3ms timing requirements

References

• WHATWG HTML Living Standard - Workers - Authoritative worker lifecycle and API specification
• WHATWG HTML - Structured Clone Algorithm - Data serialization specification
• W3C CSS Painting API Level 1 - Paint Worklet specification
• W3C CSS Animation Worklet API - Animation Worklet specification
• W3C Web Audio API - AudioWorklet - Audio Worklet specification
• MDN - Web Workers API - Comprehensive API reference
• MDN - Transferable Objects - Transferable types reference
• web.dev - Cross-Origin Isolation Guide - COOP/COEP implementation guide
• web.dev - Module Workers - Module worker usage patterns
• MDN - Houdini APIs - Worklet ecosystem overview