MessagePorts in Electron

    Here is a very brief example of what a MessagePort is and how it works:

    renderer.js (Renderer Process)

    main.js (Main Process)

    1. // In the main process, we receive the port.
    2. ipcMain.on('port', (event) => {
    3.   // When we receive a MessagePort in the main process, it becomes a
    4.   // MessagePortMain.
    5.   const port = event.ports[0]
    7.   // MessagePortMain uses the Node.js-style events API, rather than the
    8.   // web-style events API. So .on('message', ...) instead of .onmessage = ...
    9.   port.on('message', (event) => {
    10.     // data is { answer: 42 }
    11.     const data = event.data
    12.   })
    14.   // MessagePortMain queues messages until the .start() method has been called.
    15.   port.start()
    16. })

    The Channel Messaging API documentation is a great way to learn more about how MessagePorts work.

    In the renderer, the MessagePort class behaves exactly as it does on the web. The main process is not a web page, though—it has no Blink integration—and so it does not have the MessagePort or MessageChannel classes. In order to handle and interact with MessagePorts in the main process, Electron adds two new classes: MessagePortMain and . These behave similarly to the analogous classes in the renderer.

    MessagePort objects can be created in either the renderer or the main process, and passed back and forth using the ipcRenderer.postMessage and methods. Note that the usual IPC methods like send and invoke cannot be used to transfer MessagePorts, only the postMessage methods can transfer MessagePorts.

    By passing MessagePorts via the main process, you can connect two pages that might not otherwise be able to communicate (e.g. due to same-origin restrictions).

    Electron adds one feature to MessagePort that isn’t present on the web, in order to make MessagePorts more useful. That is the close event, which is emitted when the other end of the channel is closed. Ports can also be implicitly closed by being garbage-collected.

    In this example, the main process sets up a MessageChannel, then sends each port to a different renderer. This allows renderers to send messages to each other without needing to use the main process as an in-between.

    main.js (Main Process)

    1. const { BrowserWindow, app, MessageChannelMain } = require('electron')
    3. app.whenReady().then(async () => {
    4.   // create the windows.
    5.   const mainWindow = new BrowserWindow({
    6.     show: false,
    7.     webPreferences: {
    8.       contextIsolation: false,
    9.       preload: 'preloadMain.js'
    10.     }
    11.   })
    13.   const secondaryWindow = new BrowserWindow({
    14.     show: false,
    15.     webPreferences: {
    16.       contextIsolation: false,
    17.       preload: 'preloadSecondary.js'
    18.     }
    19.   })
    21.   // set up the channel.
    22.   const { port1, port2 } = new MessageChannelMain()
    24.   // once the webContents are ready, send a port to each webContents with postMessage.
    25.   mainWindow.once('ready-to-show', () => {
    26.     mainWindow.webContents.postMessage('port', null, [port1])
    27.   })
    29.   secondaryWindow.once('ready-to-show', () => {
    30.     secondaryWindow.webContents.postMessage('port', null, [port2])
    31.   })
    32. })

    Then, in your preload scripts you receive the port through IPC and set up the listeners.

    preloadMain.js and preloadSecondary.js (Preload scripts)

    1. const { ipcRenderer } = require('electron')
    3. ipcRenderer.on('port', e => {
    4.   // port received, make it globally available.
    7.   window.electronMessagePort.onmessage = messageEvent => {
    8.     // handle message
    9.   }
    10. })

    In this example messagePort is bound to the window object directly. It is better to use contextIsolation and set up specific contextBridge calls for each of your expected messages, but for the simplicity of this example we don’t. You can find an example of context isolation further down this page at

    That means window.electronMessagePort is globally available and you can call postMessage on it from anywhere in your app to send a message to the other renderer.

    renderer.js (Renderer Process)

    In this example, your app has a worker process implemented as a hidden window. You want the app page to be able to communicate directly with the worker process, without the performance overhead of relaying via the main process.

    2. app.whenReady().then(async () => {
    3.   // The worker process is a hidden BrowserWindow, so that it will have access
    4.   // to a full Blink context (including e.g. <canvas>, audio, fetch(), etc.)
    5.   const worker = new BrowserWindow({
    6.     show: false,
    7.     webPreferences: { nodeIntegration: true }
    8.   })
    9.   await worker.loadFile('worker.html')
    11.   // The main window will send work to the worker process and receive results
    12.   // over a MessagePort.
    13.   const mainWindow = new BrowserWindow({
    14.     webPreferences: { nodeIntegration: true }
    15.   })
    16.   mainWindow.loadFile('app.html')
    18.   // We can't use ipcMain.handle() here, because the reply needs to transfer a
    19.   // MessagePort.
    20.   // Listen for message sent from the top-level frame
    21.   mainWindow.webContents.mainFrame.on('request-worker-channel', (event) => {
    22.     // Create a new channel ...
    23.     const { port1, port2 } = new MessageChannelMain()
    24.     // ... send one end to the worker ...
    25.     worker.webContents.postMessage('new-client', null, [port1])
    26.     // ... and the other end to the main window.
    27.     event.senderFrame.postMessage('provide-worker-channel', null, [port2])
    28.     // Now the main window and the worker can communicate with each other
    29.     // without going through the main process!
    30.   })
    31. })

    worker.html

    1. <script>
    2. const { ipcRenderer } = require('electron')
    4. const doWork = (input) => {
    5.   // Something cpu-intensive.
    6.   return input * 2
    7. }
    9. // We might get multiple clients, for instance if there are multiple windows,
    10. // or if the main window reloads.
    11. ipcRenderer.on('new-client', (event) => {
    12.   const [ port ] = event.ports
    13.   port.onmessage = (event) => {
    14.     // The event data can be any serializable object (and the event could even
    15.     // carry other MessagePorts with it!)
    16.     const result = doWork(event.data)
    17.     port.postMessage(result)
    18.   }
    19. })
    20. </script>

    app.html

    1. <script>
    2. const { ipcRenderer } = require('electron')
    4. // We request that the main process sends us a channel we can use to
    5. // communicate with the worker.
    6. ipcRenderer.send('request-worker-channel')
    8. ipcRenderer.once('provide-worker-channel', (event) => {
    9.   // Once we receive the reply, we can take the port...
    10.   const [ port ] = event.ports
    11.   // ... register a handler to receive results ...
    13.     console.log('received result:', event.data)
    14.   }
    15.   port.postMessage(21)
    16. })
    17. </script>

    Electron’s built-in IPC methods only support two modes: fire-and-forget (e.g. send), or request-response (e.g. invoke). Using MessageChannels, you can implement a “response stream”, where a single request responds with a stream of data.

    renderer.js (Renderer Process)

    main.js (Main Process)

    1. ipcMain.on('give-me-a-stream', (event, msg) => {
    2.   // The renderer has sent us a MessagePort that it wants us to send our
    3.   // response over.
    4.   const [replyPort] = event.ports
    6.   // Here we send the messages synchronously, but we could just as easily store
    7.   // the port somewhere and send messages asynchronously.
    8.   for (let i = 0; i < msg.count; i++) {
    9.     replyPort.postMessage(msg.element)
    10.   }
    12.   // We close the port when we're done to indicate to the other end that we
    13.   // won't be sending any more messages. This isn't strictly necessary--if we
    14.   // didn't explicitly close the port, it would eventually be garbage
    15.   // collected, which would also trigger the 'close' event in the renderer.
    16.   replyPort.close()
    17. })

    When is enabled, IPC messages from the main process to the renderer are delivered to the isolated world, rather than to the main world. Sometimes you want to deliver messages to the main world directly, without having to step through the isolated world.

    main.js (Main Process)

    1. const { BrowserWindow, app, MessageChannelMain } = require('electron')
    2. const path = require('path')
    4. app.whenReady().then(async () => {
    5.   // Create a BrowserWindow with contextIsolation enabled.
    6.   const bw = new BrowserWindow({
    7.     webPreferences: {
    8.       contextIsolation: true,
    9.       preload: path.join(__dirname, 'preload.js')
    10.     }
    11.   })
    12.   bw.loadURL('index.html')
    14.   // We'll be sending one end of this channel to the main world of the
    15.   // context-isolated page.
    16.   const { port1, port2 } = new MessageChannelMain()
    18.   // It's OK to send a message on the channel before the other end has
    19.   // registered a listener. Messages will be queued until a listener is
    20.   // registered.
    21.   port2.postMessage({ test: 21 })
    23.   // We can also receive messages from the main world of the renderer.
    24.   port2.on('message', (event) => {
    25.     console.log('from renderer main world:', event.data)
    26.   })
    27.   port2.start()
    29.   // The preload script will receive this IPC message and transfer the port
    30.   // over to the main world.
    31.   bw.webContents.postMessage('main-world-port', null, [port1])
    32. })

    preload.js (Preload Script)

    1. const { ipcRenderer } = require('electron')
    3. // We need to wait until the main world is ready to receive the message before
    4. // sending the port. We create this promise in the preload so it's guaranteed
    5. // to register the onload listener before the load event is fired.
    6. const windowLoaded = new Promise(resolve => {
    7.   window.onload = resolve
    8. })
    10. ipcRenderer.on('main-world-port', async (event) => {
    11.   await windowLoaded
    12.   // We use regular window.postMessage to transfer the port from the isolated
    13.   // world to the main world.