DEV Community: mp3sss

Mastering Electron's Process Model: A Practical Guide to Secure, Maintainable IPC

mp3sss — Fri, 30 Oct 2026 01:31:58 +0000

Mastering Electron's Process Model: A Practical Guide to Secure, Maintainable IPC

Every Electron developer eventually hits the same wall: your renderer needs something from the operating system, and the only sanctioned path is IPC. Done casually, IPC becomes a swamp of stringly-typed channels, dangling listeners, and security holes. Done well, it becomes the backbone of an app that stays maintainable for years.

This guide is the mental model I wish someone had given me when I started shipping Electron apps. It covers the process model itself, the three IPC patterns that cover ~95% of real-world needs, the preload bridge, and the concrete traps that show up in production — with code you can actually run.

1. The Process Model, Properly Understood

Electron is not "a browser with Node attached." It is a multiprocess runtime with three cooperating process types — plus a fourth you will meet eventually:

Process	Runs	Can access
Main	Node.js runtime	Everything: OS APIs, file system, native modules, all windows
Renderer	Chromium (web) runtime	DOM, web APIs only — no Node by default
Preload	Sandboxed bridge	A narrow, explicit API surface you define
Utility	Node.js runtime	Heavy background work you don't want in main

The architectural insight: the renderer is untrusted territory. Even your own UI code runs with web-level privileges, because that is what keeps your users safe from XSS. Never design IPC as if the renderer were your friend — design it as if it were a hostile web page, because any injection turns it into one.

2. The Preload Bridge: Your Only Sanctioned Door

Modern Electron defaults (contextIsolation: true, nodeIntegration: false, sandbox: true) mean the renderer has no direct path to Node. The door is the preload script, which runs with access to contextBridge and ipcRenderer:

// preload.js
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('appBridge', {
  getConfig: () => ipcRenderer.invoke('config:get'),
  runExport: (path) => ipcRenderer.invoke('export:run', path),
  onExportProgress: (callback) => {
    const listener = (_event, percent) => callback(percent);
    ipcRenderer.on('export:progress', listener);
    return () => ipcRenderer.removeListener('export:progress', listener);
  },
});

Three rules make this bridge safe:

Expose functions, never objects with raw methods. Flat functions are hard to misuse.
Whitelist everything. Never do ipcRenderer passthrough helpers like invoke(channel, ...args) — that turns your bridge into a remote-control for the main process.
Return an unsubscribe function. Every on you expose must give the caller a way to unregister, or you will leak listeners across window reloads.

3. Three IPC Patterns That Cover 95% of Use Cases

Pattern A — Request/Response (`invoke`/`handle`)

For any call that returns data, use the promise-based pair. It is the most common pattern and the one you should reach for first:

// main.js
const { ipcMain } = require('electron');

ipcMain.handle('config:get', async () => {
  return await loadConfig(); // returns a plain, cloneable object
});

// renderer (through the bridge above)
const config = await window.appBridge.getConfig();

Use handle, not on+send+event.reply, for anything request-like. The promise lifecycle gives you automatic error propagation and avoids the classic "reply goes to the wrong window" bug.

Pattern B — Fire-and-Forget Events (`send`/`on`)

For commands where the renderer does not need an answer — log flushing, analytics pings, "open this file in the default app":

ipcMain.on('log:flush', (event, entry) => {
  appendToLogFile(entry);
});

Renderer side: ipcRenderer.send('log:flush', entry).

One rule saves you weeks: never use send when you need the result. Mixing fire-and-forget with event.sender.send() replies creates race conditions that are brutal to reproduce.

Pattern C — Main → Renderer Streams

For progress, logs, or live data pushed from main, keep the channel name scoped and the payload small:

function streamProgress(webContents, percent) {
  webContents.send('export:progress', percent);
}

Renderer subscribes through the bridge (see the unsubscribe pattern above). If you find yourself pushing large payloads (file contents, image buffers) over these channels, stop and use a file path or a custom protocol instead — IPC payloads go through structured clone and will eat memory and jank your UI.

4. Payload Discipline: What You Can (and Can't) Send

IPC serializes arguments with the structured clone algorithm. That means:

Plain objects, arrays, strings, numbers, booleans, Date, Map, Set, ArrayBuffer/TypedArray (copied, not shared)
Functions, class instances, prototypes, DOM nodes are rejected
Circular references — supported but a code smell
Large buffers — copied, so 50 MB through IPC costs you 50 MB in each process

Practical consequences:

Never pass secrets or tokens the renderer doesn't need. The renderer is not trusted; if you don't need it there, don't send it.
Never pass file paths you intend to also validate later. Validate before you let a path travel, then treat the received path as data from an untrusted caller (because it is).
For big files, send a path + token and let main do the work, or use protocol.handle() with a custom scheme for streaming reads.

5. Security Hardening: Validate the Sender

The single most-ignored IPC rule is validating who is talking to you. Any window or frame can invoke your handlers — including one compromised by XSS, or a stray BrowserWindow you created for a third-party page. Minimum viable protection:

ipcMain.handle('export:run', async (event, path) => {
  // Check the frame is your app's trusted top frame before acting
  if (event.senderFrame?.url && !isAllowedRendererURL(event.senderFrame.url)) {
    throw new Error('Unauthorized sender');
  }
  return runExport(path);
});

Beyond that:

Prefer per-channel allowlists over global checks.
Use webContents.getURL() at send time, never trust a stale variable.
For high-value operations (payments, destructive actions, credential reads), require an explicit user gesture and re-confirm in the UI.
Keep webSecurity on. Disabling it to "make dev easier" ships as a production vulnerability more often than people admit.

6. Concurrency and Backpressure

IPC handlers are async and can be called concurrently. Two things will bite you:

1. Shared state races. If two renderers both invoke('config:save') concurrently, last-write-wins may corrupt the file. Serialize mutations through a queue in main:

let writeQueue = Promise.resolve();
function saveConfigSerialized(data) {
  writeQueue = writeQueue.then(() => persist(data));
  return writeQueue;
}

2. Event flood. A renderer spamming send('log:flush', ...) can starve the main process. Throttle or batch on the main side — or simply don't build unbounded per-window channels.

7. Memory Leaks: The Silent Production Killer

The most common leak in Electron apps is invisible to the renderer and ignored by the profiler until the app slows to a crawl:

Listeners registered in main per-window and never removed when the window closes or reloads.
ipcMain.on handlers that capture large objects and outlive their windows.
Renderer listeners attached through the bridge without the unsubscribe being called on HMR/unmount.

The discipline that fixes all three — tie handler lifecycle to the window, and always return an unsubscribe from the bridge. In a React renderer:

useEffect(() => {
  const unsubscribe = window.appBridge.onExportProgress(setPercent);
  return unsubscribe; // called on unmount — non-negotiable
}, []);

8. A Minimal Complete Example

Here is a small but complete skeleton combining everything above:

// main.js
const { app, BrowserWindow, ipcMain } = require('electron');
const path = require('path');

let exportProgress = 0;

function createWindow() {
  const win = new BrowserWindow({
    width: 900, height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false,
      sandbox: true,
    },
  });
  win.loadFile('index.html');
}

ipcMain.handle('export:run', async (event, { format, pages }) => {
  if (!isTrustedFrame(event)) throw new Error('Unauthorized');
  for (let i = 0; i < pages; i++) {
    exportProgress = Math.round(((i + 1) / pages) * 100);
    event.sender.send('export:progress', exportProgress);
    await new Promise((r) => setTimeout(r, 100)); // simulated work
  }
  return { ok: true, format };
});

app.whenReady().then(() => {
  createWindow();
  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow();
  });
});

9. When to Reach for Utility Processes

Long-running CPU work (image encoding, zip, parsing huge logs) should not run in main — it blocks the event loop and freezes every window. Options, in order of preference:

utilityProcess.fork() — Node.js child, shared binary, ideal for CPU jobs.
worker_threads — but note: Electron renderer workers are Chromium Web Workers, not Node threads.
child_process.fork() — fine, but heavier and harder to manage lifecycle.

Rule of thumb: if a handler takes longer than ~50 ms or uses more than one CPU core, it does not belong in the main process's event loop.

10. Checklist Before You Ship

Every channel is named domain:action, documented in one place.
No renderer can reach Node without going through a whitelisted preload function.
Every handle validates event.senderFrame (URL or app origin).
Every on/stream subscription is paired with an unsubscribe, in both processes.
Payloads are small, cloneable, and contain no secrets.
Long-running work is off the main loop.
webSecurity: true, contextIsolation: true, sandbox: true in every window — no exceptions for "that one internal page."

Final Thought

The process model is not an obstacle to your app — it is the security boundary that lets you ship a Node-powered desktop app to hostile environments. Treat IPC as an API surface with the same rigor as your backend: versioned, validated, documented, and small. Your future self, debugging a three-month-old feature at 2 a.m., will thank you.

If you found this useful, follow me — I write field-tested Electron deep-dives every week: process model, performance, packaging, security, and everything that actually breaks in production.

Electron Cross-Platform Shipping: A Field Guide to Packaging, Code Signing & Auto-Update

mp3sss — Thu, 29 Oct 2026 04:18:39 +0000

Writing an Electron app is easy. Shipping it — to real users, on Windows and macOS, without scary SmartScreen warnings or broken updates — is where most teams burn weeks.

I've spent the last two years shipping a cross-platform Electron client (Windows + macOS) to production users. This is the field guide I wish I'd had on day one: the packaging stack, the signing traps, and an auto-update flow that won't corrupt your users' installations.

1. Pick your packaging stack once

Three main options exist:

Tool	Style	Verdict
`electron-packager`	Bare-bones	Good for dev builds; you'll end up scripting everything
`electron-forge`	All-in-one	Powerful, but heavier to configure for advanced signing
`electron-builder`	Declarative config	The pragmatic default — one config file drives installers, signing, and publishing

I recommend electron-builder for most teams. It handles NSIS installers on Windows, DMG/ZIP on macOS, code signing, and publishing to update servers through a single electron-builder.yml. You don't need to be an installer expert to ship with it.

Key decision: electron-builder can also sign your binaries during packaging — a huge win, because signing after modifying the binary is a classic source of broken builds (more on that later).

2. Windows: SmartScreen, certificates, and the "Windows protected your PC" wall

If you ship an unsigned Windows build, your users will see this:

Windows protected your PC — Microsoft Defender SmartScreen prevented an unrecognized app from starting.

For a non-technical user, that screen is a conversion killer. Unsigned builds are for internal testing only.

OV vs EV certificates

OV (Organization Validation) — cheaper, issued in days. After you've signed enough installers, SmartScreen reputation builds up and warnings fade.
EV (Extended Validation) — expensive, hardware token required, instant reputation. If you're a startup with a small install base, EV is the shortcut past the "new publisher" trust problem.

Practical note: the timestamp server matters more than people think. If you don't timestamp, your signature expires when the certificate does. Always timestamp:

# electron-builder.yml
win:
  target:
    - target: nsis
      arch: [x64, arm64]
  certificateFile: ./certs/win-cert.pfx
  certificatePassword: ${env.WIN_CERT_PASSWORD}
  signtoolOptions:
    signWithParams: /tr http://timestamp.digicert.com /td sha256 /fd sha256

SmartScreen reality check

Even with a valid OV signature, the first few thousand installs may still show a warning until Microsoft's reputation engine recognizes your publisher. Don't panic — this is normal. Ship, collect reputation, and re-evaluate EV if installs stall.

NSIS installers: one-way upgrades

Use NSIS with oneClick: false if you want a per-user/per-machine choice. Keep the installerIcon and uninstallerIcon custom — tiny details that make your installer look professional rather than default.

3. macOS: signing, notarization, and the Gatekeeper gauntlet

macOS is the stricter platform by far. Since Catalina, every app must be notarized or users face an "cannot be opened because the developer cannot be verified" block.

The three-step dance

Sign your app bundle with a Developer ID Application certificate.
Notarize it — upload to Apple's notary service, wait for approval.
Staple the notarization ticket to the app so it validates offline.

Hardened runtime & entitlements

If you enable the hardened runtime (required for notarization), you must declare entitlements — otherwise your app may crash at launch on the user's machine while working fine on yours. The classic missing entitlement:

<!-- entitlements.mac.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
    <true/>
    <key>com.apple.security.cs.disable-library-validation</key>
    <true/>
</dict>
</plist>

Warning: If your app spawns helper binaries or uses native modules, disable-library-validation is frequently required — but it weakens security. Add it deliberately, document why, and remove it if you can.

electron-builder config for macOS

mac:
  target:
    - target: dmg
      arch: [x64, arm64]
  category: public.app-category.developer-tools
  hardenedRuntime: true
  entitlements: ./entitlements.mac.plist
  entitlementsInherit: ./entitlements.mac.plist
  notarize:
    teamId: ${env.APPLE_TEAM_ID}
    appleId: ${env.APPLE_ID}
    appleIdPassword: ${env.APPLE_APP_SPECIFIC_PASSWORD}

The traps that cost days

"Certificate not found in keychain" — the certificate's private key must be in the login keychain of the machine doing the build, not the System keychain, and its type must be "Developer ID Application" (not "Developer ID Installer" — they look similar).
CI machines lose keychains constantly. Export the certificate as a .p12 and import it in your build step, or use a signing service.
Apple ID with 2FA — you must use an app-specific password, never your account password.
Notarization latency — allow 5–15 minutes per submission. Batch it into your release pipeline, not your pre-release "ship now" hour.

4. Auto-update that doesn't break users

The fastest way to lose trust is an update that bricks your app. Here's a flow that has survived production for two years.

Use `electron-updater`

npm i electron-updater

const { autoUpdater } = require("electron-updater");

autoUpdater.autoDownload = true;
autoUpdater.autoInstallOnAppQuit = true;

// Only check when the app is foregrounded or on a timer — never at every boot.
autoUpdater.checkForUpdatesAndNotify();

Config it with a plain file server (nginx, S3, any static host):

publish:
  provider: generic
  url: https://updates.example.com/releases

Differential updates

electron-builder generates .blockmap files that let electron-updater download only the changed bytes — typically 5–20% of the full package for a normal release. This is the single biggest win for update speed.

Rollback safety

Three rules keep updates from becoming outages:

Never delete the previous version's files on the server. Keep at least the last two releases so a bad rollout can be rolled back by re-publishing the old latest.yml.
Validate the downloaded package before install — electron-updater verifies the signature/hash automatically. Don't disable it.
Ship updates to a percentage of users for risky releases, then ramp up. Electron apps have no built-in percentage rollout — implement a simple "update channel" by environment variable or server-side allowlist if you need it.

Version numbering

electron-updater compares semver strictly. 1.0.10 is newer than 1.0.9; a 1.0.9.5 four-part version will confuse comparisons. Enforce MAJOR.MINOR.PATCH everywhere — package.json, the updater, and your release tooling.

5. Versioning & CI: make releases boring

The release process should be one command, run by a pipeline, not a person.

GitHub Actions matrix example

name: Release
on:
  push:
    tags: ["v*"]
jobs:
  build:
    strategy:
      matrix:
        os: [windows-latest, macos-latest]
        arch: [x64, arm64]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx electron-builder --publish always
        env:
          WIN_CERT_PASSWORD: ${{ secrets.WIN_CERT_PASSWORD }}
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}

Cache & artifact hygiene

Cache node_modules per-OS (native modules are platform-specific).
Only sign once, on the final packaged artifact — never sign a zip, then unzip, modify, and re-sign. Re-signing after modification invalidates the seal and Gatekeeper will reject it.
Keep a release checklist in your repo: "tag → pipeline → smoke test on a clean Windows VM and a clean macOS VM → announce."

6. The real-world pitfall list

Bugs I actually hit, in roughly the order they'll hit you:

SmartScreen warning on first release even with OV cert — fixed by patience + EV evaluation.
macOS app crashes only on users' machines — root cause: missing entitlements for JIT/native modules under hardened runtime.
Update loop after bad release — users stuck on broken version; fixed by keeping old latest.yml and re-publishing previous release.
Windows Defender false positives — Electron apps occasionally trip heuristics, especially with unsigned helper executables. Submit to Microsoft for review; keep signing everything including helpers.
CI "certificate not found" — keychain not imported in fresh runners; fixed with a .p12 import step.
DMG name with spaces breaking update paths — normalize filenames to AppName-1.2.3.dmg strictly. Spaces in update URLs are a silent source of 404s.
ARM64 vs x64 update mixing — electron-updater picks the right arch automatically from package.json arch field, but only if you publish both variants. Check your latest-mac.yml / latest.yml list both.

7. TL;DR — if you remember five things

electron-builder + electron-updater is the stack that works.
Sign everything, every time, with timestamps — on Windows and macOS.
macOS = sign → notarize → staple, and never modify the bundle after signing.
Keep the last two releases on the server — rollback is your safety net.
Strict semver or the updater will fight you.

Shipping a cross-platform Electron app is a solved problem — but only if you treat packaging and distribution as a first-class engineering concern, not an afterthought. Automate it, sign it, and your users will never think about it. That's the whole point.

Have your own shipping war stories? Drop them in the comments — the worst ones are the most instructive.

DEV Community: mp3sss

Mastering Electron's Process Model: A Practical Guide to Secure, Maintainable IPC

Mastering Electron's Process Model: A Practical Guide to Secure, Maintainable IPC

1. The Process Model, Properly Understood

2. The Preload Bridge: Your Only Sanctioned Door

3. Three IPC Patterns That Cover 95% of Use Cases

Pattern A — Request/Response (invoke/handle)

Pattern B — Fire-and-Forget Events (send/on)

Pattern C — Main → Renderer Streams

4. Payload Discipline: What You Can (and Can't) Send

5. Security Hardening: Validate the Sender

6. Concurrency and Backpressure

7. Memory Leaks: The Silent Production Killer

8. A Minimal Complete Example

9. When to Reach for Utility Processes

10. Checklist Before You Ship

Final Thought

Electron Cross-Platform Shipping: A Field Guide to Packaging, Code Signing & Auto-Update

1. Pick your packaging stack once

2. Windows: SmartScreen, certificates, and the "Windows protected your PC" wall

OV vs EV certificates

SmartScreen reality check

NSIS installers: one-way upgrades

3. macOS: signing, notarization, and the Gatekeeper gauntlet

The three-step dance

Hardened runtime & entitlements

electron-builder config for macOS

The traps that cost days

4. Auto-update that doesn't break users

Use electron-updater

Differential updates

Rollback safety

Version numbering

5. Versioning & CI: make releases boring

GitHub Actions matrix example

Cache & artifact hygiene

6. The real-world pitfall list

7. TL;DR — if you remember five things

Pattern A — Request/Response (`invoke`/`handle`)

Pattern B — Fire-and-Forget Events (`send`/`on`)

Use `electron-updater`