Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Web APIs in Node.js

Node.js BroadcastChannel class

Reference for the BroadcastChannel class in Node.js: send messages to every channel with the same name across the main thread and worker threads.

A BroadcastChannel is a named group chat for threads. Every BroadcastChannel object created with the same name, in the main thread or in any worker thread of the same process, receives each message that any other member posts. It is a convenient publish/subscribe tool when several workers must hear the same news, such as "configuration changed" or "shut down".

The sender does not receive its own message; only the other channel objects with that name do. Messages are copied with the structured clone algorithm, like postMessage() on a MessagePort. BroadcastChannel is a global and works across threads only: it does not reach other processes.

NODE
const channel = new BroadcastChannel('news');
channel.onmessage = (event) => console.log(event.data);
channel.postMessage('hello'); // delivered to other members, not to this object

Try it

Node.js Two channels in one thread

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Announcing to workers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
new BroadcastChannel(name)
Member Description
name Read-only name. Converted to a string. Channels with equal names are connected.
postMessage(message) Send a copy of message to all other channels with the same name. Returns undefined.
close() Disconnect this object and release its resources.
onmessage, onmessageerror Handler properties; addEventListener('message', ...) works too.
ref(), unref() Node extensions: unref() lets the process exit even when the channel is open; ref() undoes it.

Handlers receive a MessageEvent; the payload is in event.data. onmessageerror fires when a message cannot be deserialized.

Errors: postMessage() throws DataCloneError (a DOMException) when the value cannot be cloned (functions, symbols, some host objects) and InvalidStateError after close(). Constructing without a name throws TypeError.

Usage notes

  • The sender never hears itself. If a component both sends and listens, create two BroadcastChannel objects, or use a message type that shows who sent it.
  • An open channel with a listener keeps the process alive. Close it when you are done, or call unref() for background listeners that should not block exit.
  • There is no delivery guarantee for late joiners. A channel only receives messages posted after it was created. There is no history, acknowledgement or ordering across different senders.
  • Messages are copied, so large payloads cost time and memory for every receiver. Send small notifications and let workers fetch big data from shared storage (for example a SharedArrayBuffer).
  • It is process-local. It does not work across child_process forks, cluster workers or separate Node processes; use IPC, sockets or a message broker for those.
  • Name collisions connect unrelated code. Use specific names such as myapp:config so a library inside your process does not receive your messages.
  • Compared with MessageChannel: a MessageChannel links exactly two ports and can transfer ports and buffers; BroadcastChannel links any number of members by name and never transfers.