From a550dd4b8b0803a977282d7d0d023f9286a10967 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Thu, 24 Jul 2025 08:02:04 -0700 Subject: [PATCH 1/2] Document MessageChannel/MessagePort --- .../workers/runtime-apis/messagechannel.mdx | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 src/content/docs/workers/runtime-apis/messagechannel.mdx 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 00000000000000..42c440cff95d24 --- /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. From 1689fb3c8d3f808b2c00110e2181982a3bbf70ed Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 11 Aug 2025 16:26:27 -0700 Subject: [PATCH 2/2] Changelog entry for MessageChannel --- .../workers/2025-08-11-messagechannel.mdx | 41 +++++++++++++++++++ src/content/release-notes/workers.yaml | 3 ++ 2 files changed, 44 insertions(+) create mode 100644 src/content/changelog/workers/2025-08-11-messagechannel.mdx 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 00000000000000..b73740d15413af --- /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/release-notes/workers.yaml b/src/content/release-notes/workers.yaml index fe92c6846197df..ab633e55fea324 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.