Skip to content

Commit b6a7ab5

Browse files
authored
docs: relay flow documentation (PlasmoHQ#117)
- Expanded introduction to explain `relayMessage` and its abstraction of `window.postMessage`. - Detailed forwarding of messages to background service worker and processing by message flow handlers. - Introduced `sendToBackgroundViaRelay` for sending messages and awaiting responses, with unique instance ID handling. - Added GitHub link for viewing function implementations. - Highlighted as an alternative to the "externally_connectable" Chrome extension method. - Provided detailed steps for setting up a relay with `relayMessage`. - Completed instructions on sending messages using `sendToBackgroundViaRelay`.
1 parent 3daf87c commit b6a7ab5

File tree

1 file changed

+13
-3
lines changed

1 file changed

+13
-3
lines changed

src/pages/framework/messaging.mdx

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -143,9 +143,19 @@ console.log(resp)
143143

144144
</Callout>
145145

146-
Use the Relay Flow to communicate between a target webpage and the background service worker. A relay is a lightweight message handler registered using a [content script](/framework/content-scripts). It listens for messages from the target webpage and pipes them down to the [Message Flow's handlers](#message-flow).
146+
The Relay Flow enables communication between a target webpage and a background service worker using a lightweight message handler called a relay. This relay is registered with the `relayMessage` function in a [content script](/framework/content-scripts).
147147

148-
Create a relay inside a content script. The `relayMessage` function takes a message name. A content script can have multiple relays. Given the `ping` message handler from the previous example, and the website `www.plasmo.com`:
148+
The `relayMessage` function abstracts the `window.postMessage` mechanism, registering a listener that checks for messages matching the same origin and forwards them to the background service worker. These messages are then processed by the appropriate [message flow handlers](#message-flow) registered under `background/messages`.
149+
150+
The `sendToBackgroundViaRelay` function sends messages through the relay and waits for a response. It generates a unique instance ID for each message to ensure proper handling and response tracking.
151+
152+
You may view the implementation of these functions in the [GitHub repository](https://github.com/PlasmoHQ/plasmo/blob/main/api/messaging/src/relay.ts).
153+
154+
This method provides an alternative to the ["externally_connectable"](https://developer.chrome.com/docs/extensions/develop/concepts/messaging#external-webpage) method described in the Chrome extension documentation.
155+
156+
### Setting Up a Relay
157+
158+
To set up a relay, use the `relayMessage` function in a content script. A content script can have multiple relays. Given the `ping` message handler from the previous example, and the website `www.plasmo.com`:
149159

150160
```ts filename="contents/plasmo.ts"
151161
import type { PlasmoCSConfig } from "plasmo"
@@ -161,7 +171,7 @@ relayMessage({
161171
})
162172
```
163173

164-
- On the `plasmo.com` web page, you can send messages via the relay:
174+
In the code of the target webpage (e.g., `plasmo.com`), you can send messages using the registered relay using `sendToBackgroundViaRelay` as follows:
165175

166176
```tsx filename="pages/index.tsx"
167177

0 commit comments

Comments
 (0)