Web Workers

A second thread for heavy work

A thread is a line of work that the computer runs one step at a time. Every browser page has one main line of work, called the main thread. It does most of the page's jobs:

• It runs most of your JavaScript.
• It reacts to clicks and key presses.
• It changes the DOM, the tree of elements that make up the page.
• It works out the layout and paints the screen.

The main thread does one job at a time. If your code runs a long calculation there, every other job waits. Clicks do nothing. Animations stop. The page feels stuck.

A Web Worker is a second place to run JavaScript, on another thread. While the worker calculates, the main thread stays free for clicks and painting. This lesson uses dedicated workers. A dedicated worker belongs to the one page that made it.

The page and the worker don't share variables, and the worker can't touch the DOM. They talk by sending messages to each other with postMessage.

In this lesson you will learn:

• how to create a worker, send it work, and stop it;
• how messages are copied on the way (this is called structured clone);
• how to hand data over without copying it (transferable objects);
• the two kinds of worker: classic workers and module workers.

The lesson also uses the event loop: the way the browser picks the next job to run, one at a time. If that idea is new, keep the Event loop lesson open beside this one.

You make a dedicated worker with new Worker(url). The url is the address of the worker's own JavaScript file. In a real app, your bundler (the build tool that packs your files) often makes that address for you.

The playgrounds on this page can't load extra files. So each one puts its worker code into a Blob URL. A Blob URL is a short-lived address that the browser makes for text kept in memory.

The code below shows both sides. The top part runs on the page. The bottom part runs inside the worker.

1// main.js2const worker = new Worker(workerUrl);3 4worker.postMessage({ type: "count", limit: 120000 });5 6worker.onmessage = (event) => {7  renderResult(event.data);8};9 10worker.onerror = (event) => {11  console.error(event.message);12};13 14// worker.js15self.onmessage = (event) => {16  const result = doHeavyWork(event.data.limit);17  self.postMessage(result);18};

Line by line:

• Line 2 creates the worker.
• Line 4 sends it a message: an object that asks it to count up to 120000.
• Lines 6 to 8 run when the worker replies. The reply is in event.data.
• Lines 10 to 12 run if the worker's code throws an error.
• Lines 15 to 18 are the worker's side. self is the worker's own global object, like window on a page. When a message arrives, the worker does the work and sends the result back with self.postMessage.

The next code puts the page's side in order. Line 1 creates the worker. Lines 2 and 3 set up the reply and error handlers first. Line 4 sends the work. Line 7 stops the worker later, once its work is no longer needed.

1const worker = new Worker(workerUrl);2worker.onmessage = (event) => console.log(event.data);3worker.onerror = (event) => console.error(event.message);4worker.postMessage({ type: "count", limit: 10 });5 6// Later, when this work is stale:7worker.terminate();

A dedicated worker has many of the tools a page has. It has:

• postMessage and onmessage, for messages;
• timers such as setTimeout;
• fetch, for network requests;
• IndexedDB, the browser's built-in database.

It does not have document, the page's window, the layout, or your React state.

Two events on the Worker object tell you something went wrong:

• error fires when the worker's code throws, or when its script fails to load.
• messageerror fires when a message arrives but can't be turned back into a value.

One more problem shows up sooner. If postMessage can't copy a value, it throws an error right away, on the side that sent it.

Jank means the page stutters or freezes because the screen wasn't redrawn in time. To show it, this lab counts prime numbers: numbers that divide evenly only by 1 and by themselves. Counting them is pure JavaScript work. It needs no network, only the computer's processor, the CPU.

Try it:

1. Click Run on main thread. The moving dot stops until the count ends.
2. Click Run in worker. The same count runs in a worker, and the dot keeps moving.

1function countPrimesUpTo(limit) {2  let count = 0;3  for (let value = 2; value <= limit; value += 1) {4    if (isPrime(value)) count += 1;5  }6  return count;7}8 9// Main thread: blocks clicks, animation, and paint until done.10const total = countPrimesUpTo(120000);11 12// Worker thread: the same CPU work runs away from the UI.13worker.postMessage({ type: "count", limit: 120000 });

The worker still uses the CPU. The work doesn't disappear. The gain is that the main thread stays free for clicks and painting.

Workers also cost something. Starting a worker takes time, and so does sending each message. So don't make a worker for every small loop.

To send a message, one side calls postMessage(value). A moment later, the other side gets a message event. The value is in the event's data property, event.data.

The value itself doesn't travel. The browser makes a copy of it, using a fixed list of steps called structured clone. Structured clone can copy more kinds of values than JSON can:

• dates (Date);
• Map and Set;
• ArrayBuffer, a block of raw bytes;
• arrays and plain objects, even nested ones.

You can run the same copy steps yourself with structuredClone(value). The small example below uses it to show what a worker would get.

1const order = { item: "tea" };2const copy = structuredClone(order);3order.item = "coffee";4console.log(copy.item);5console.log(order.item);

Line by line:

• Line 1 makes an order object with item: "tea".
• Line 2 makes a separate copy, copy.
• Line 3 changes the original to "coffee".
• Line 4 prints tea, because the copy didn't change. Line 5 prints coffee.

A worker works the same way. It gets the value as it was when you posted it. Later changes to the original don't reach it.

1const original = {2  created: new Date("2026-09-25T08:30:00.000Z"),3  labels: new Map([["level", "warm-up"]]),4  nested: ["ticket", { count: 1 }],5};6 7worker.postMessage(original);8original.nested[1].count = 99;9 10// The worker receives a structured-clone copy with count still 1.11worker.postMessage(() => "functions cannot be cloned");

Copying is fine for small values. For a big block of bytes, copying takes time and uses twice the memory. Some objects are transferable. The browser moves them to the receiver instead of copying them, and the sender gives them up. These are transferable:

• ArrayBuffer, a block of raw bytes;
• MessagePort, one end of a private message channel;
• ImageBitmap, an image that is ready to draw;
• OffscreenCanvas, a canvas that can draw away from the page.

After you transfer an ArrayBuffer, the sender's buffer is detached: it is empty. Its byteLength, the number of bytes it holds, becomes 0.

1const buffer = new ArrayBuffer(4);2const copy = structuredClone(buffer, { transfer: [buffer] });3console.log(buffer.byteLength);4console.log(copy.byteLength);

Line by line:

• Line 1 makes a buffer that holds 4 bytes.
• Line 2 passes it to structuredClone with the option { transfer: [buffer] }. That option says: move this buffer, don't copy it. With a worker, you write the same thing as worker.postMessage(buffer, [buffer]).
• Line 3 prints 0. The sender's buffer is empty now.
• Line 4 prints 4. The receiver has the bytes.

So never transfer a buffer that the page still needs to read.

1const buffer = new ArrayBuffer(4 * 1024 * 1024);2 3worker.postMessage({ buffer });4console.log(buffer.byteLength); // sender still owns it5 6const fastBuffer = new ArrayBuffer(4 * 1024 * 1024);7worker.postMessage({ buffer: fastBuffer }, [fastBuffer]);8console.log(fastBuffer.byteLength); // 0: ownership transferred

There is one way to truly share memory: SharedArrayBuffer. Both sides read and write the same bytes. Browsers allow it only on pages that are cross-origin isolated. That means the server sends two special response headers:

• Cross-Origin-Opener-Policy: same-origin
• Cross-Origin-Embedder-Policy: require-corp

Check the global crossOriginIsolated before you use SharedArrayBuffer. This page's code editor runs in a locked-down frame on purpose, so it doesn't have it. Shared memory is an advanced topic. Copying and transferring cover most needs.

There are two kinds of worker. They differ only in how they load code:

• A classic worker is made with new Worker(url). It loads a normal script. To load more scripts, it calls importScripts("helper.js"). That loads and runs each script at once, before the next line runs.
• A module worker is made with new Worker(url, { type: "module" }). It loads a JavaScript module, so it can use import and export in browsers that support them.

1const classic = new Worker(classicUrl);2// classic workers use importScripts("helper.js") when they need scripts.3 4try {5  const moduleWorker = new Worker(moduleUrl, { type: "module" });6  moduleWorker.postMessage("ping");7} catch (error) {8  console.log("module workers are not available here");9}

Both kinds follow the same safety rule: neither one can touch the DOM. The choice is only about how your code is loaded and bundled.

In a real project, check two things:

• how your bundler makes worker URLs;
• your site's Content Security Policy (CSP): rules that say where the page may load scripts from. Some CSPs block blob: workers.

This site's CSP doesn't block blob: workers, so the labs can use Blob URLs. After a lab stops a worker, it also revokes (cancels) the worker's Blob URL. Then the browser can let go of the script text.

importScripts() works only in classic workers. A module worker uses import lines at the top of the file instead. Mixing the two is a common bug when a project switches from classic to module workers.

postMessage doesn't call the worker right away. It puts the message in a queue, a waiting line, and returns. Then things happen in this order:

1. The rest of the current script keeps running.
2. Microtasks, such as promise callbacks, run right after the script, as usual (see the Promises lesson).
3. The worker's onmessage runs later, in the worker's own event loop.
4. The worker's reply comes back even later, as a new message event on the Worker object.

Step through the code below and watch when each line runs.

1const ticket = { items: ["salad", "soup"] };Run2console.log("main: before postMessage");3worker.postMessage(ticket);4ticket.items.push("pie");5console.log("main: changed original");6 7// later, in the worker event loop8self.onmessage = (event) => {9  console.log(event.data.items.join(", "));10  self.postMessage("done");11};

Workers are best for jobs that:

• take a lot of CPU time;
• don't need the DOM;
• take data in and give data back.

Some examples: reading a big file, searching many records, making small preview images, compressing images, crunching numbers, or sorting a very large table.

A normal fetch already waits without blocking the main thread. A worker helps only if the response needs heavy work afterward.

A SharedWorker is a different kind of worker. Several pages from the same site (the same origin) can connect to one shared worker. Each page talks to it through its own MessagePort, the page's end of a message channel.

• Inside the shared worker, a connect event fires for each page that connects.
• Each port must be started with start(), or given an onmessage handler, before messages flow.

Use a shared worker to coordinate several pages, not as a faster dedicated worker.

1const shared = new SharedWorker("shared-worker.js");2shared.port.onmessage = (event) => console.log(event.data);3shared.port.start();4shared.port.postMessage({ type: "lookup", key: "tea" });5 6// shared-worker.js7self.onconnect = (event) => {8  const port = event.ports[0];9  port.onmessage = () => port.postMessage("ready");10};

This example can't run here. It needs a separate shared-worker.js file on a real site. The dedicated Blob workers above are the ones that run on this page.

1const names = ["Grace", "Ada", "Linus", "Brendan", "Hedy"];2 3// Small list: keep it simple.4const sortedHere = [...names].sort((a, b) => a.localeCompare(b));5 6// Large list: send a copy and render the reply.7worker.postMessage(names);8worker.onmessage = (event) => renderRows(event.data);

The table below compares the two threads. Read each row as a question, then the answer for each side.

Common misconceptions

• "Workers can update the page." They can't touch the DOM. The worker sends a message back, and the main thread updates the page.
• "Workers make code faster." They keep the page free to respond. The total time may get shorter, stay the same, or even get longer for small jobs.
• "Messages share objects." Normal messages are copies. Later changes to the original don't reach the copy.
• "A transfer is just a faster copy." A transfer moves the object. The sender no longer has it.
• "A worker can hide secrets." Worker code and its messages still run in the user's browser, where the user can read them.
• "Service workers are the same thing." A dedicated worker helps one page calculate. A service worker sits between your pages and the network. That is the next lesson.

Key takeaways

• A dedicated worker lets a page run long calculations away from the main thread, so the page stays free to respond.
• The page and the worker talk with postMessage. A normal message is a structured-clone copy.
• A transfer moves an object instead of copying it. A transferred ArrayBuffer is left empty on the sender's side.
• Workers have timers, fetch, and IndexedDB, but no DOM.
• Stop workers with terminate() when their work is out of date, and listen for error events.

Up next: Service workers and offline apps.