Electron IPC Breakdown: When main and renderer stop talking

Since Electron 12, contextIsolation defaults to true. This means the renderer process runs in a separate JavaScript context from the preload script—they do not share variables or globals. The only way to pass functions or data from preload to renderer is via contextBridge.exposeInMainWorld. If you omit that call, the renderer has no access to ipcRenderer at all, and all IPC calls fail silently. Many devs forget this after upgrading from older Electron versions where nodeIntegration was true.

To inspect the bridge, open DevTools on the renderer and type window.electronAPI (or whatever key you used in exposeInMainWorld). If it's undefined, your preload either didn't run, crashed, or the key is wrong. Also check the preload script's Source in DevTools—if it's not listed, the path is incorrect. A common mistake is setting preload to a relative path like './preload.js'—this works in dev but fails in production because the working directory changes. Always use path.join(__dirname, 'preload.js') or an absolute path.

When the preload script throws an exception (e.g., TypeError, ReferenceError, or missing module), Electron does not surface that error to the renderer console by default. The preload runs before the renderer's window is created, so any error is swallowed. The only symptom is that contextBridge.exposeInMainWorld never executes, leaving window.electronAPI undefined. To catch these, wrap your entire preload code in a try/catch and log to stderr: try { ... } catch(e) { console.error(e); }. This error appears in the renderer DevTools console.

Common preload crashes include: using require('fs') or other Node modules that are not allowed in sandboxed preloads; referencing an undefined variable; or calling ipcRenderer methods before the module is loaded. Also, if you use TypeScript, ensure the compiled preload.js is correct and doesn't contain import statements that fail at runtime. Always test the preload by running the app in dev and checking for any console errors.

Even with a correctly working preload, IPC can fail due to channel name mismatches. A typo like 'my-channel' vs 'my_channel' causes the message to be sent to a listener that doesn't exist. Since there is no error for an unhandled IPC channel, this appears as a silent failure. To debug, add a catch-all listener in main: ipcMain.on('*', (event, channel, ...args) => console.log('IPC:', channel, args)). This logs every incoming message, helping you spot mismatches.

Timing is another culprit. If the main process sends a message via webContents.send before the renderer's IPC listener is registered, the message is lost. Always ensure the renderer's listener is set up before main sends—for example, by having the renderer send a 'ready' message first, or by using 'did-finish-load' event in main to delay sending. Also, if the renderer is a single-page app with navigation, the listener might be destroyed and not re-registered—use persistent listeners on the window object.

IPC that works in development can break after packaging with electron-builder or electron-packager. The most common reason is the preload script path. In development, __dirname points to the project root, but in production, it points to the app.asar directory. A relative path like './preload.js' might resolve to the wrong location or fail to load entirely. Use path.join(__dirname, 'preload.js')—this works in both dev and production. Also ensure the preload file is included in the build's resources (it usually is, but check the builder config).

Another production issue: if you use environment variables or Node modules that are not bundled, they may be missing in the packaged app. For example, using a .env file with dotenv—make sure it's included. Also, if you use native Node modules (like serialport), they need to be rebuilt for the target platform. Test the packaged build early in your CI pipeline to catch these failures before they reach users.

Content Security Policy (CSP) headers or meta tags can block the execution of the preload script or inline scripts in the renderer. Electron sets a default CSP, but if you override it, you might inadvertently block the bridge. For example, setting 'script-src' without 'unsafe-inline' can break contextBridge. Check your CSP in the renderer's network tab or by inspecting the meta tag. If CSP is too restrictive, the preload script may not execute, and you'll see a CSP violation in the console.

Also, if you enable sandbox: true in webPreferences, the preload script runs with limited capabilities. Some APIs like require are disabled. In sandboxed preloads, you can only use a subset of Node.js modules. Ensure your preload doesn't rely on restricted modules. If you need full Node.js access, set sandbox: false, but this has security implications. The secure approach is to design your preload to only use contextBridge and ipcRenderer.