Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Worker.postMessage — sending data to a worker

Worker.postMessage sends data to a dedicated worker through an asynchronous message channel. Data is structured-cloned, while an optional transfer list lets you transfer resources such as ArrayBuffer instead of copying them.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

worker.postMessage(message)
worker.postMessage(message, transfer)
worker.postMessage(message, { transfer })

Worker.postMessage denotes an instance method of Worker, not a static constructor method. Calling worker.postMessage(message) sends data to a dedicated worker. A successful call does not guarantee delivery: the worker may terminate before the event is dispatched. If deserialization fails on the receiving side, the receiver gets a messageerror event instead of message. When the receiver gets a message event, it reads the data from event.data. The method returns undefined, not a Promise; returning does not mean the receiver has finished its work.

The message is structured-cloned, not serialized through JSON. Plain objects and arrays are supported, among other values; functions are unsupported and cause a synchronous DataCloneError exception. Do not assume custom class prototypes will be preserved. Delivery is asynchronous, but serialization happens during the call and can impose work on the sender.

The optional second argument is a transfer list or an object { transfer }. Transferring an ArrayBuffer detaches the sender's buffer: its byteLength then becomes 0. The buffer must also be reachable from message if the receiver is to access it; the transfer list alone does not add it to the message data. Transfer a typed array's buffer, not the typed array itself as a transfer-list item.

Send a reply inside the worker using self.postMessage(...) and receive it on the worker object. This is not window.postMessage: there is no targetOrigin argument. SharedWorker uses worker.port.postMessage(...). HTML Living Standard defines this API, not an ECMAScript edition. The basic method is supported in modern browser engines; check compatibility for the transfer form you use separately. Node 24 does not establish availability of this browser API.

Examples

const source = `
self.onmessage = ({ data }) => {
  const values = new Uint8Array(data);
  self.postMessage(values[0] + values[1]);
};
`;
const url = URL.createObjectURL(new Blob([source], {
  type: 'text/javascript'
}));
const worker = new Worker(url);
const cleanup = () => {
  worker.terminate();
  URL.revokeObjectURL(url);
};
worker.onmessage = ({ data }) => {
  console.log('sum:', data);
  cleanup();
};
worker.onerror = () => {
  console.error('Worker failed');
  cleanup();
};
worker.onmessageerror = () => {
  console.error('Message decoding failed');
  cleanup();
};
const buffer = new Uint8Array([20, 22]).buffer;
worker.postMessage(buffer, [buffer]);
console.log('sender bytes:', buffer.byteLength);

Result

sender bytes: 0
sum: 42

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources