Inter-Process Communication

    In Electron, processes communicate by passing messages through developer-defined “channels” with the and ipcRenderer modules. These channels are arbitrary (you can name them anything you want) and bidirectional (you can use the same channel name for both modules).

    In this guide, we’ll be going over some fundamental IPC patterns with concrete examples that you can use as a reference for your app code.

    Understanding context-isolated processes

    Before proceeding to implementation details, you should be familiar with the idea of using a preload script to import Node.js and Electron modules in a context-isolated renderer process.

    • For a full overview of Electron’s process model, you can read the .
    • For a primer into exposing APIs from your preload script using the contextBridge module, check out the context isolation tutorial.

    To fire a one-way IPC message from a renderer process to the main process, you can use the ipcRenderer.send API to send a message that is then received by the API.

    You usually use this pattern to call a main process API from your web contents. We’ll demonstrate this pattern by creating a simple app that can programmatically change its window title.

    For this demo, you’ll need to add code to your main process, your renderer process, and a preload script. The full code is below, but we’ll be explaining each file individually in the following sections.

    docs/fiddles/ipc/pattern-1 (23.0.0)

    • main.js
    • preload.js
    • index.html
    • renderer.js
    1. const { contextBridge, ipcRenderer } = require('electron')
    3. contextBridge.exposeInMainWorld('electronAPI', {
    4.     setTitle: (title) => ipcRenderer.send('set-title', title)
    5. })
    1. <!DOCTYPE html>
    2. <html>
    3.   <head>
    4.     <meta charset="UTF-8">
    5.     <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    6.     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    7.     <title>Hello World!</title>
    8.   </head>
    9.   <body>
    10.     Title: <input id="title"/>
    11.     <button id="btn" type="button">Set</button>
    12.     <script src="./renderer.js"></script>
    13.   </body>
    14. </html>
    1. const setButton = document.getElementById('btn')
    2. const titleInput = document.getElementById('title')
    3. setButton.addEventListener('click', () => {
    4.     const title = titleInput.value
    5.     window.electronAPI.setTitle(title)
    6. });

    In the main process, set an IPC listener on the set-title channel with the ipcMain.on API:

    main.js (Main Process)

    1. const {app, BrowserWindow, ipcMain} = require('electron')
    2. const path = require('path')
    4. //...
    6. function handleSetTitle (event, title) {
    7.   const webContents = event.sender
    8.   const win = BrowserWindow.fromWebContents(webContents)
    9.   win.setTitle(title)
    10. }
    12. function createWindow () {
    13.   const mainWindow = new BrowserWindow({
    14.     webPreferences: {
    15.       preload: path.join(__dirname, 'preload.js')
    16.     }
    17.   })
    18.   mainWindow.loadFile('index.html')
    19. }
    21. app.whenReady().then(() => {
    22.   ipcMain.on('set-title', handleSetTitle)
    23.   createWindow()
    24. }
    25. //...

    The above handleSetTitle callback has two parameters: an structure and a title string. Whenever a message comes through the set-title channel, this function will find the BrowserWindow instance attached to the message sender and use the win.setTitle API on it.

    info

    Make sure you’re loading the index.html and preload.js entry points for the following steps!

    2. Expose ipcRenderer.send via preload

    To send messages to the listener created above, you can use the ipcRenderer.send API. By default, the renderer process has no Node.js or Electron module access. As an app developer, you need to choose which APIs to expose from your preload script using the contextBridge API.

    In your preload script, add the following code, which will expose a global window.electronAPI variable to your renderer process.

    preload.js (Preload Script)

    1. const { contextBridge, ipcRenderer } = require('electron')
    3. contextBridge.exposeInMainWorld('electronAPI', {
    4.     setTitle: (title) => ipcRenderer.send('set-title', title)
    5. })

    At this point, you’ll be able to use the window.electronAPI.setTitle() function in the renderer process.

    Inter-Process Communication - 图2Security warning

    We don’t directly expose the whole ipcRenderer.send API for . Make sure to limit the renderer’s access to Electron APIs as much as possible.

    3. Build the renderer process UI

    In our BrowserWindow’s loaded HTML file, add a basic user interface consisting of a text input and a button:

    index.html

    1. <!DOCTYPE html>
    2. <html>
    3.   <head>
    4.     <meta charset="UTF-8">
    5.     <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    6.     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    7.     <title>Hello World!</title>
    8.   </head>
    9.   <body>
    10.     Title: <input id="title"/>
    11.     <button id="btn" type="button">Set</button>
    12.     <script src="./renderer.js"></script>
    13.   </body>
    14. </html>

    To make these elements interactive, we’ll be adding a few lines of code in the imported renderer.js file that leverages the window.electronAPI functionality exposed from the preload script:

    renderer.js (Renderer Process)

    1. const setButton = document.getElementById('btn')
    2. const titleInput = document.getElementById('title')
    3. setButton.addEventListener('click', () => {
    4.     const title = titleInput.value
    5.     window.electronAPI.setTitle(title)
    6. });

    At this point, your demo should be fully functional. Try using the input field and see what happens to your BrowserWindow title!

    Pattern 2: Renderer to main (two-way)

    A common application for two-way IPC is calling a main process module from your renderer process code and waiting for a result. This can be done by using ipcRenderer.invoke paired with .

    In the following example, we’ll be opening a native file dialog from the renderer process and returning the selected file’s path.

    For this demo, you’ll need to add code to your main process, your renderer process, and a preload script. The full code is below, but we’ll be explaining each file individually in the following sections.

    docs/fiddles/ipc/pattern-2 (23.0.0)

    • main.js
    • preload.js
    • index.html
    • renderer.js
    1. const {app, BrowserWindow, ipcMain, dialog} = require('electron')
    2. const path = require('path')
    4. async function handleFileOpen() {
    5.   const { canceled, filePaths } = await dialog.showOpenDialog()
    6.     return
    7.   } else {
    8.     return filePaths[0]
    9.   }
    10. }
    12. function createWindow () {
    13.   const mainWindow = new BrowserWindow({
    14.     webPreferences: {
    15.       preload: path.join(__dirname, 'preload.js')
    16.     }
    17.   })
    18.   mainWindow.loadFile('index.html')
    19. }
    21. app.whenReady().then(() => {
    22.   ipcMain.handle('dialog:openFile', handleFileOpen)
    23.   createWindow()
    24.   app.on('activate', function () {
    25.     if (BrowserWindow.getAllWindows().length === 0) createWindow()
    26.   })
    27. })
    30.   if (process.platform !== 'darwin') app.quit()
    31. })
    1. const { contextBridge, ipcRenderer } = require('electron')
    3. contextBridge.exposeInMainWorld('electronAPI',{
    4.   openFile: () => ipcRenderer.invoke('dialog:openFile')
    5. })
    1. const btn = document.getElementById('btn')
    2. const filePathElement = document.getElementById('filePath')
    4. btn.addEventListener('click', async () => {
    5.   const filePath = await window.electronAPI.openFile()
    6.   filePathElement.innerText = filePath
    7. })

    In the main process, we’ll be creating a handleFileOpen() function that calls dialog.showOpenDialog and returns the value of the file path selected by the user. This function is used as a callback whenever an ipcRender.invoke message is sent through the dialog:openFile channel from the renderer process. The return value is then returned as a Promise to the original invoke call.

    Errors thrown through handle in the main process are not transparent as they are serialized and only the message property from the original error is provided to the renderer process. Please refer to for details.

    main.js (Main Process)

    1. const { BrowserWindow, dialog, ipcMain } = require('electron')
    2. const path = require('path')
    4. //...
    6. async function handleFileOpen() {
    7.   const { canceled, filePaths } = await dialog.showOpenDialog()
    8.   if (canceled) {
    9.     return
    10.   } else {
    11.     return filePaths[0]
    12.   }
    13. }
    15. function createWindow () {
    16.   const mainWindow = new BrowserWindow({
    17.     webPreferences: {
    18.       preload: path.join(__dirname, 'preload.js')
    19.     }
    20.   })
    21.   mainWindow.loadFile('index.html')
    22. }
    24. app.whenReady(() => {
    25.   ipcMain.handle('dialog:openFile', handleFileOpen)
    26.   createWindow()
    27. })
    28. //...

    on channel names

    The dialog: prefix on the IPC channel name has no effect on the code. It only serves as a namespace that helps with code readability.

    Inter-Process Communication - 图5info

    Make sure you’re loading the index.html and preload.js entry points for the following steps!

    2. Expose ipcRenderer.invoke via preload

    In the preload script, we expose a one-line openFile function that calls and returns the value of ipcRenderer.invoke('dialog:openFile'). We’ll be using this API in the next step to call the native dialog from our renderer’s user interface.

    preload.js (Preload Script)

    1. const { contextBridge, ipcRenderer } = require('electron')
    3. contextBridge.exposeInMainWorld('electronAPI', {
    4.   openFile: () => ipcRenderer.invoke('dialog:openFile')
    5. })

    Security warning

    We don’t directly expose the whole ipcRenderer.invoke API for . Make sure to limit the renderer’s access to Electron APIs as much as possible.

    3. Build the renderer process UI

    Finally, let’s build the HTML file that we load into our BrowserWindow.

    index.html

    1. <!DOCTYPE html>
    2. <html>
    3.   <head>
    4.     <meta charset="UTF-8">
    5.     <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    6.     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    7.     <title>Dialog</title>
    8.   </head>
    9.   <body>
    10.     <button type="button" id="btn">Open a File</button>
    11.     File path: <strong id="filePath"></strong>
    12.     <script src='./renderer.js'></script>
    13.   </body>
    14. </html>

    The UI consists of a single #btn button element that will be used to trigger our preload API, and a #filePath element that will be used to display the path of the selected file. Making these pieces work will take a few lines of code in the renderer process script:

    renderer.js (Renderer Process)

    1. const btn = document.getElementById('btn')
    2. const filePathElement = document.getElementById('filePath')
    4. btn.addEventListener('click', async () => {
    5.   const filePath = await window.electronAPI.openFile()
    6.   filePathElement.innerText = filePath
    7. })

    In the above snippet, we listen for clicks on the #btn button, and call our window.electronAPI.openFile() API to activate the native Open File dialog. We then display the selected file path in the #filePath element.

    The ipcRenderer.invoke API was added in Electron 7 as a developer-friendly way to tackle two-way IPC from the renderer process. However, there exist a couple alternative approaches to this IPC pattern.

    Inter-Process Communication - 图7Avoid legacy approaches if possible

    We recommend using ipcRenderer.invoke whenever possible. The following two-way renderer-to-main patterns are documented for historical purposes.

    info

    For the following examples, we’re calling ipcRenderer directly from the preload script to keep the code samples small.

    Using ipcRenderer.send

    The ipcRenderer.send API that we used for single-way communication can also be leveraged to perform two-way communication. This was the recommended way for asynchronous two-way communication via IPC prior to Electron 7.

    preload.js (Preload Script)

    1. // You can also put expose this code to the renderer
    2. // process with the `contextBridge` API
    3. const { ipcRenderer } = require('electron')
    5. ipcRenderer.on('asynchronous-reply', (_event, arg) => {
    6.   console.log(arg) // prints "pong" in the DevTools console
    7. })
    8. ipcRenderer.send('asynchronous-message', 'ping')

    main.js (Main Process)

    1. ipcMain.on('asynchronous-message', (event, arg) => {
    2.   console.log(arg) // prints "ping" in the Node console
    3.   // works like `send`, but returning a message back
    4.   // to the renderer that sent the original message
    5.   event.reply('asynchronous-reply', 'pong')
    6. })

    There are a couple downsides to this approach:

    • You need to set up a second ipcRenderer.on listener to handle the response in the renderer process. With invoke, you get the response value returned as a Promise to the original API call.
    • There’s no obvious way to pair the asynchronous-reply message to the original asynchronous-message one. If you have very frequent messages going back and forth through these channels, you would need to add additional app code to track each call and response individually.

    Using ipcRenderer.sendSync

    The ipcRenderer.sendSync API sends a message to the main process and waits synchronously for a response.

    main.js (Main Process)

    1. const { ipcMain } = require('electron')
    2. ipcMain.on('synchronous-message', (event, arg) => {
    3.   event.returnValue = 'pong'
    4. })

    preload.js (Preload Script)

    1. // You can also put expose this code to the renderer
    2. // process with the `contextBridge` API
    3. const { ipcRenderer } = require('electron')
    5. const result = ipcRenderer.sendSync('synchronous-message', 'ping')
    6. console.log(result) // prints "pong" in the DevTools console

    The structure of this code is very similar to the invoke model, but we recommend avoiding this API for performance reasons. Its synchronous nature means that it’ll block the renderer process until a reply is received.

    To demonstrate this pattern, we’ll be building a number counter controlled by the native operating system menu.

    For this demo, you’ll need to add code to your main process, your renderer process, and a preload script. The full code is below, but we’ll be explaining each file individually in the following sections.

    Open in Fiddle

    • main.js
    • preload.js
    • index.html
    • renderer.js
    1. const { contextBridge, ipcRenderer } = require('electron')
    3. contextBridge.exposeInMainWorld('electronAPI', {
    5. })
    1. <!DOCTYPE html>
    2. <html>
    3.   <head>
    4.     <meta charset="UTF-8">
    5.     <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    6.     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    7.     <title>Menu Counter</title>
    8.   </head>
    9.   <body>
    10.     Current value: <strong id="counter">0</strong>
    11.     <script src="./renderer.js"></script>
    12.   </body>
    13. </html>
    1. const counter = document.getElementById('counter')
    3. window.electronAPI.handleCounter((event, value) => {
    4.     const oldValue = Number(counter.innerText)
    5.     const newValue = oldValue + value
    6.     counter.innerText = newValue
    7.     event.sender.send('counter-value', newValue)
    8. })

    1. Send messages with the webContents module

    For this demo, we’ll need to first build a custom menu in the main process using Electron’s Menu module that uses the webContents.send API to send an IPC message from the main process to the target renderer.

    main.js (Main Process)

    1. const {app, BrowserWindow, Menu, ipcMain} = require('electron')
    2. const path = require('path')
    4. function createWindow () {
    5.   const mainWindow = new BrowserWindow({
    6.     webPreferences: {
    7.       preload: path.join(__dirname, 'preload.js')
    8.     }
    9.   })
    11.   const menu = Menu.buildFromTemplate([
    12.     {
    13.       label: app.name,
    14.       submenu: [
    15.         {
    16.           click: () => mainWindow.webContents.send('update-counter', 1),
    17.           label: 'Increment',
    18.         },
    19.         {
    20.           click: () => mainWindow.webContents.send('update-counter', -1),
    21.           label: 'Decrement',
    22.         }
    23.       ]
    24.     }
    25.   ])
    26.   Menu.setApplicationMenu(menu)
    28.   mainWindow.loadFile('index.html')
    29. }
    30. //...

    For the purposes of the tutorial, it’s important to note that the click handler sends a message (either 1 or -1) to the renderer process through the update-counter channel.

    1. click: () => mainWindow.webContents.send('update-counter', -1)

    Inter-Process Communication - 图9info

    Make sure you’re loading the index.html and preload.js entry points for the following steps!

    2. Expose ipcRenderer.on via preload

    Like in the previous renderer-to-main example, we use the contextBridge and ipcRenderer modules in the preload script to expose IPC functionality to the renderer process:

    preload.js (Preload Script)

    1. const { contextBridge, ipcRenderer } = require('electron')
    3. contextBridge.exposeInMainWorld('electronAPI', {
    4.     onUpdateCounter: (callback) => ipcRenderer.on('update-counter', callback)
    5. })

    After loading the preload script, your renderer process should have access to the window.electronAPI.onUpdateCounter() listener function.

    Security warning

    We don’t directly expose the whole ipcRenderer.on API for . Make sure to limit the renderer’s access to Electron APIs as much as possible.

    Inter-Process Communication - 图11info

    In the case of this minimal example, you can call ipcRenderer.on directly in the preload script rather than exposing it over the context bridge.

    preload.js (Preload Script)

    1. const { ipcRenderer } = require('electron')
    3. window.addEventListener('DOMContentLoaded', () => {
    4.     const counter = document.getElementById('counter')
    5.     ipcRenderer.on('update-counter', (_event, value) => {
    6.         const oldValue = Number(counter.innerText)
    7.         const newValue = oldValue + value
    8.         counter.innerText = newValue
    9.     })
    10. })

    However, this approach has limited flexibility compared to exposing your preload APIs over the context bridge, since your listener can’t directly interact with your renderer code.

    To tie it all together, we’ll create an interface in the loaded HTML file that contains a #counter element that we’ll use to display the values:

    index.html

    1. <!DOCTYPE html>
    2. <html>
    3.   <head>
    4.     <meta charset="UTF-8">
    5.     <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    6.     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    7.     <title>Menu Counter</title>
    8.   </head>
    9.   <body>
    10.     Current value: <strong id="counter">0</strong>
    11.     <script src="./renderer.js"></script>
    12.   </body>
    13. </html>

    Finally, to make the values update in the HTML document, we’ll add a few lines of DOM manipulation so that the value of the #counter element is updated whenever we fire an update-counter event.

    renderer.js (Renderer Process)

    1. const counter = document.getElementById('counter')
    3. window.electronAPI.onUpdateCounter((_event, value) => {
    4.     const oldValue = Number(counter.innerText)
    5.     const newValue = oldValue + value
    6.     counter.innerText = newValue
    7. })

    In the above code, we’re passing in a callback to the window.electronAPI.onUpdateCounter function exposed from our preload script. The second value parameter corresponds to the 1 or -1 we were passing in from the webContents.send call from the native menu.

    Optional: returning a reply

    There’s no equivalent for ipcRenderer.invoke for main-to-renderer IPC. Instead, you can send a reply back to the main process from within the ipcRenderer.on callback.

    We can demonstrate this with slight modifications to the code from the previous example. In the renderer process, use the event parameter to send a reply back to the main process through the counter-value channel.

    renderer.js (Renderer Process)

    In the main process, listen for counter-value events and handle them appropriately.

    main.js (Main Process)

    1. //...
    2. ipcMain.on('counter-value', (_event, value) => {
    3.   console.log(value) // will print value to Node console
    4. })
    5. //...

    Pattern 4: Renderer to renderer

    There’s no direct way to send messages between renderer processes in Electron using the ipcMain and ipcRenderer modules. To achieve this, you have two options:

    • Use the main process as a message broker between renderers. This would involve sending a message from one renderer to the main process, which would forward the message to the other renderer.

    In particular, DOM objects (e.g. Element, Location and DOMMatrix), Node.js objects backed by C++ classes (e.g. process.env, some members of Stream), and Electron objects backed by C++ classes (e.g. WebContents, and WebFrame) are not serializable with Structured Clone.