diff --git a/src/content/changelog/workers/2025-08-11-messagechannel.mdx b/src/content/changelog/workers/2025-08-11-messagechannel.mdx new file mode 100644 index 000000000000000..b73740d15413afb --- /dev/null +++ b/src/content/changelog/workers/2025-08-11-messagechannel.mdx @@ -0,0 +1,41 @@ +--- +title: MessageChannel and MessagePort +description: The MessageChannel and MessagePort APIs are now available in Workers +products: + - workers +date: 2025-08-11T01:00:00Z +--- + +A minimal implementation of the [MessageChannel API](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel) is now available in Workers. This means that you can use `MessageChannel` to send messages between different parts of your Worker, but not across different Workers. + +The `MessageChannel` and `MessagePort` APIs will be available by default at the global scope +with any worker using a compatibility date of `2025-08-15` or later. It is also available +using the `expose_global_message_channel` compatibility flag, or can be explicitly disabled +using the `no_expose_global_message_channel` compatibility flag. + +```js +const { port1, port2 } = new MessageChannel(); + +port2.onmessage = (event) => { + console.log('Received message:', event.data); +}; + +port2.postMessage('Hello from port2!'); +``` + +Any value that can be used with the `structuredClone(...)` API can be sent over the port. + +## Differences + +There are a number of key limitations to the `MessageChannel` API in Workers: + +* Transfer lists are currently not supported. This means that you will not be able to transfer + ownership of objects like `ArrayBuffer` or `MessagePort` between ports. +* The `MessagePort` is not yet serializable. This means that you cannot send a `MessagePort` object + through the `postMessage` method or via JSRPC calls. +* The `'messageerror'` event is only partially supported. If the `'onmessage'` handler throws an + error, the `'messageerror'` event will be triggered, however, it will not be triggered when there + are errors serializing or deserializing the message data. Instead, the error will be thrown when + the `postMessage` method is called on the sending port. +* The `'close'` event will be emitted on both ports when one of the ports is closed, however it + will not be emitted when the Worker is terminated or when one of the ports is garbage collected. diff --git a/src/content/docs/workers/runtime-apis/messagechannel.mdx b/src/content/docs/workers/runtime-apis/messagechannel.mdx new file mode 100644 index 000000000000000..42c440cff95d245 --- /dev/null +++ b/src/content/docs/workers/runtime-apis/messagechannel.mdx @@ -0,0 +1,41 @@ +--- +pcx_content_type: configuration +title: MessageChannel +head: [] +description: Channel messaging with MessageChannel and MessagePort + +--- + +## Background + +The [MessageChannel API](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel) provides a way to create a communication channel between different parts of your application. + +The Workers runtime provides a minimal implementation of the `MessageChannel` API that is +currently limited to uses with a single Worker instance. This means that you can use `MessageChannel` to send messages between different parts of your Worker, but not across different Workers. + +```js +const { port1, port2 } = new MessageChannel(); + +port2.onmessage = (event) => { + console.log('Received message:', event.data); +}; + +port2.postMessage('Hello from port2!'); +``` + +Any value that can be used with the `structuredClone(...)` API can be sent over the port. + +## Differences + +There are a number of key limitations to the `MessageChannel` API in Workers: + +* Transfer lists are currently not supported. This means that you will not be able to transfer + ownership of objects like `ArrayBuffer` or `MessagePort` between ports. +* The `MessagePort` is not yet serializable. This means that you cannot send a `MessagePort` object + through the `postMessage` method or via JSRPC calls. +* The `'messageerror'` event is only partially supported. If the `'onmessage'` handler throws an + error, the `'messageerror'` event will be triggered, however, it will not be triggered when there + are errors serializing or deserializing the message data. Instead, the error will be thrown when + the `postMessage` method is called on the sending port. +* The `'close'` event will be emitted on both ports when one of the ports is closed, however it + will not be emitted when the Worker is terminated or when one of the ports is garbage collected. diff --git a/src/content/release-notes/workers.yaml b/src/content/release-notes/workers.yaml index fe92c6846197dff..ab633e55fea3244 100644 --- a/src/content/release-notes/workers.yaml +++ b/src/content/release-notes/workers.yaml @@ -3,6 +3,9 @@ link: "/workers/platform/changelog/" productName: Workers productLink: "/workers/" entries: + - publish_date: "2025-08-11" + description: |- + - The MessageChannel and MessagePort APIs are now available in Workers. - publish_date: "2025-06-27" description: |- - Updated v8 to version 13.9.