Messaging & structured cloning

Sending data to another place

A web page often has to send data to another place. For example:

• A page sends data to an iframe: a page shown inside your page.
• A page sends work to a worker: a script that runs in the background.
• A settings tab tells your other open tabs that the theme changed.

These places can't share one object. So the browser sends them a copy of the data. For some data, it can hand the data over instead.

The browser copies the data with a set of rules called the structured clone algorithm. "Clone" means copy. The same rules are used by:

• structuredClone(), which copies a value inside one script.
• postMessage(), which sends a message to a window, an iframe, or a worker.
• MessagePort and BroadcastChannel, two more ways to send messages.
• IndexedDB, the browser's database, when it saves a value.

These rules copy many kinds of JavaScript values. They can even copy an object that points to itself. For some binary data, they can also transfer it: hand it over instead of copying it.

When you send a message to another window, say who may receive it. The second argument of postMessage is the target origin. An origin is the start of a web address: the scheme, host, and port, like https://widget.example. The browser delivers the message only if the receiving window has that origin. Never use "*", which means "any origin", for a secret message.

When you receive a message, check two things before you trust event.data:

• event.origin: the origin of the page that sent it.
• event.source: the window that sent it.

The code below is a small model of those two checks.

1const trustedOrigin = "https://widget.example";2const trustedWindow = "widget-window";3const event = { origin: trustedOrigin, source: trustedWindow, data: { type: "ready" } };4 5function receive(event) {6  if (event.origin !== trustedOrigin || event.source !== trustedWindow) return "ignored";7  return event.data.type;8}9 10console.log(receive(event));11console.log(receive({ ...event, origin: "https://evil.example" }));

Line 6 returns "ignored" if the origin or the window is wrong. Line 10 passes the trusted message, so it prints ready. Line 11 sends the same message from https://evil.example, so it prints ignored.

The model uses plain strings in place of real windows, so it gives the same result every time. In a real page, use the iframe or popup window you created in place of trustedWindow. When you send, pass the same trusted origin as the second argument of postMessage.

The Windows, iframes & postMessage lesson showed how to send a message. This lesson is about the data inside the message: what can be copied, what can't, and what can be handed over.

structuredClone(value) makes a deep copy of a value. A deep copy copies the object and everything inside it, so the copy shares nothing with the original. It uses the same rules as messages.

You may know JSON.stringify and JSON.parse from the JSON lesson. JSON turns data into text and back, and many types get lost on the way. structuredClone keeps them. It can copy:

• Date, Map, Set, and RegExp objects.
• ArrayBuffer objects and typed arrays such as Uint8Array.
• Blob and File objects.
• Common Error objects.
• Objects that point to themselves. These are called circular references.

It copies data, not everything. It does not keep:

• The methods of your own classes. The copy doesn't get the class's prototype, the object where those methods live.
• Getters. A getter is a function that runs when you read a property.
• A property's settings, such as whether it can be changed.

It reads the object's own properties, saves their current values, and builds new objects from them.

1const cart = { items: ["tea"] };2const copy = structuredClone(cart);3copy.items.push("bread");4console.log(cart.items.join(","));5console.log(copy.items.join(","));

Line 1 makes a cart with a list of items. Line 2 copies the cart. The copy gets its own new list. Line 3 adds bread to the copy's list only. So line 4 prints tea, and line 5 prints tea,bread.

1const prices = new Map([["tea", 3]]);2const tags = new Set(["hot"]);3const copy = structuredClone({ prices, tags });4console.log(copy.prices.get("tea"));5console.log(copy.tags.has("hot"));

Line 3 copies an object that holds a Map and a Set. The copies are still a real Map and a real Set. So line 4 prints 3, and line 5 prints true. JSON would turn both of them into empty objects, {}.

1const original = makeValue(choice);2const copy = structuredClone(original);3inspect(copy);

Try the "Class instance" choice. A class instance is an object made with new from your own class. Its fields are copied, but its method is lost, because the prototype isn't copied.

Then try "Object with a getter". The getter runs once, during the copy. The copy stores the number it returned as a normal value. The getter itself is gone.

A simple rule: data can be copied, but behavior and live browser objects usually can't. Here is why each of these fails:

• A function is behavior. It also remembers the variables around it.
• A DOM node, such as a button, belongs to one live page.
• A symbol is a unique value. A copy would be a different value.
• A WeakMap or WeakSet can lose entries at any time, when the browser cleans up objects nobody uses. So its contents can't be listed and copied.

For these values, structuredClone throws a DataCloneError. It doesn't pretend it copied them.

1const order = { onDone: () => "saved" };2structuredClone(order);

The function on line 1 is behavior, not data. So line 2 throws a DataCloneError. The fix is to send plain data that names the action, such as { type: "save" }. The receiver then runs its own function for that action.

One more change to know about. A RegExp (a regular expression) is copied, but its lastIndex is set back to 0. In a global search, lastIndex is where the next search starts. So the copy starts searching from the beginning again.

new MessageChannel() makes two linked ports, port1 and port2. A port is one end of the line. Both ports are MessagePort objects. A message posted on one port arrives at the other.

You keep one port and transfer the other to a worker or an iframe. Now the two sides have a private line. They don't need the shared message listener on window any more.

1const channel = new MessageChannel();2channel.port1.onmessage = (event) => log("port1", event.data);3channel.port1.start();4iframe.contentWindow.postMessage("connect", "*", [channel.port2]);5channel.port1.postMessage("hello iframe");

The lab listens for messages in two ways. You'll see both in real code:

• The parent page uses addEventListener("message", ...). With this way, you must call port.start() before messages arrive.
• The iframe sets port.onmessage = .... Setting onmessage starts the port for you.

Calling start() when you don't need to does no harm, and it makes the code easier to read.

BroadcastChannel is for announcements to everyone, not private talks. You make one with a name, like new BroadcastChannel("updates"). Every channel with the same name on the same origin hears messages from the others. That includes channels in other tabs, windows, iframes, and workers.

The channel object that sends a message does not get its own message.

1const a = new BroadcastChannel("lesson-room");2const b = new BroadcastChannel("lesson-room");3const c = new BroadcastChannel("lesson-room");4b.onmessage = (event) => log("B heard " + event.data);5c.onmessage = (event) => log("C heard " + event.data);6a.postMessage("standup at 10");

Open this lesson in a second tab and press Create channels there too. The second tab is on the same origin, so its channels hear the messages from this tab as well.

Copying makes separate data on both sides. Transferring hands an object over: after a transfer, only the receiver can use it.

Only some objects can be transferred. They are called transferable objects. The clearest example is an ArrayBuffer, a block of raw bytes. After a transfer, the sender's buffer is detached: it is empty and can't be used. Its byteLength, the size in bytes, becomes 0. The receiver now has the bytes.

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

A transfer list is an array of the objects to hand over instead of copy. You'll use it in two places:

• structuredClone(value, { transfer: [buffer] })
• port.postMessage(value, [buffer])

Use a transfer list for big images, sound clips, or other binary data that the sender doesn't need any more.

The table compares the three tools in this lesson. Each row asks one question. Each column gives the answer for one tool.

postMessage returns right away. The receiver's message event runs later, after the current code finishes. Posting a message puts its delivery in a queue. It doesn't stop your code and jump to the receiver. The Event loop lesson explains this queue.

1const { port1, port2 } = new MessageChannel();Run2const buffer = new ArrayBuffer(4);3 4port1.onmessage = (event) => {5  console.log("message event:", event.data.byteLength);6};7 8port2.postMessage(buffer);9console.log("after postMessage:", buffer.byteLength);

The setting changes line 8. In copy mode, the sender still has its buffer, so line 9 logs 4. In transfer mode, line 8 takes the buffer away at once, so line 9 logs 0. In both modes, the receiver's event runs last and sees all 4 bytes.

You'll use these tools when a web app splits its work across several places. For example:

• A canvas sends its pixels to a worker to be changed.
• An iframe gets a private port to reply on.
• A settings page tells your other tabs to refresh.
• A worker sends back data it has read, so the page doesn't freeze while it waits.

1const worker = new Worker("image-worker.js", { type: "module" });2const pixels = canvasBuffer;3 4worker.postMessage(5  { job: "blur", width, height, pixels },6  [pixels],7);8 9worker.onmessage = (event) => {10  drawPixels(event.data.pixels);11};

Line 1 starts a worker. Lines 4–7 send it a job:

• Line 5 is the message. Small details such as width and height are copied.
• Line 6 is the transfer list. The big pixels buffer is handed over, not copied.

After sending, the page must not read pixels, because the worker now owns it. When the worker is done, it can transfer a new buffer back. Line 9 handles that reply.

Common misconceptions

Each choice explains why it is right or wrong. Read the wrong ones too: they show the most common mistakes.

Key takeaways

• structuredClone makes a deep copy. It keeps many types that JSON loses: Date, Map, Set, typed arrays, Error objects, and objects that point to themselves.
• It refuses behavior and live objects: functions, DOM nodes, symbols, WeakMap, and WeakSet.
• An object made from your own class arrives as plain data. Its methods, getters, and property settings are not kept.
• MessageChannel gives you two private ports. BroadcastChannel sends to every other channel with the same name and origin.
• A transfer list hands data over. After a transfer, the sender's ArrayBuffer has a byteLength of 0.

Up next: Web Components. You'll build your own HTML elements with custom elements, Shadow DOM, templates, and slots.