Electron Knowledge Patch

Electron Knowledge Patch

Use this skill when writing, reviewing, or upgrading Electron applications. Check the project's pinned Electron version first and apply guidance only when the relevant change has shipped in that version. Treat the application manifest, lockfile, code, and tests as authoritative when they disagree with this guidance.

Reference index

Upgrade triage

Prepare for removals

• Electron 44 removes the renderer clipboard module. Prefer navigator.clipboard, or expose narrowly scoped advanced operations from a preload with contextBridge.
• Electron 44 requires macOS 13 or later and stops publishing 32-bit companion artifacts. Electron 43 is the final prebuilt line for Windows x86 and Linux ARMv7.
• Linux showHiddenFiles was deprecated in Electron 41 and removed in Electron
  43. Do not rely on it outside macOS and Windows.
• webContents no longer emits plugin-crashed.
• PrinterInfo.isDefault and PrinterInfo.status are gone.
• Remove systemPreferences.isAeroGlassEnabled() branches; the API has no replacement.

Migrate deprecated APIs

• Replace Session.setPreloads() and getPreloads() with registerPreloadScript(), unregisterPreloadScript(), and getPreloadScripts().
• Replace session.serviceWorkers.fromVersionID() with getInfoFromVersionID() or getWorkerFromVersionID().
• Move extension methods and events from session to session.extensions.
• Replace NativeImage.getBitmap() with toBitmap().
• Replace webFrame.routingId and findFrameByRoutingId() with frameToken and findFrameByToken(); resolve main-process tokens with webFrameMain.fromFrameToken().
• Stop passing quota or quotas to Session.clearStorageData().
• Read console-message data from the event object and use lineNumber.
• Use --host-resolver-rules instead of Chromium's deprecated --host-rules.

Audit changed defaults

• An empty web-request urls array matches nothing; use ['<all_urls>'] when every URL is intended.
• Electron runs natively on Wayland when available. Pass --ozone-platform=x11 only when Xwayland behavior is required.
• Offscreen rendering uses device scale factor 1.0; set webPreferences.offscreen.deviceScaleFactor explicitly for another scale.
• window.open() popups are always resizable unless setWindowOpenHandler() overrides resizable.
• Downloads and dialogs without defaultPath start in Downloads, falling back to Home. Persist and pass a directory to retain last-used behavior.
• app.commandLine lowercases switches and arguments. Read application-specific arguments from process.argv.
• A utility-process process.exit() is synchronous, so buffered output may not flush.

Security-critical behavior

Keep renderer privileges narrow

Direct renderer access to Electron's clipboard API is deprecated before its removal. Put privileged work in the main or preload context and expose the smallest possible surface:

const { clipboard, contextBridge } = require('electron');

contextBridge.exposeInMainWorld('clipboardAPI', {
  readText: () => clipboard.readText(),
});

Sandboxed windows opened by a top-level frame inherit the opener's sandbox restrictions. <webview> and window.open() also inherit nodeIntegrationInWorker; do not assume a child silently resets security preferences.

Package and sign correctly

• Stable ASAR integrity terminates the app when the packaged archive hash is absent or mismatched. On macOS, embed the ASAR-integrity digest and re-sign.
• macOS notifications require a code-signed application; unsigned apps emit failed instead of displaying the notification.
• Desktop capture with audio on macOS 14.2 or later needs NSAudioCaptureUsageDescription or the CoreAudio Tap path can return silent audio without an error.
• allowExtensions: true is required when Chrome extensions must access a privileged custom protocol.

High-value APIs

Diagnose hung and failed renderers

To collect a JavaScript stack from an unresponsive renderer, enable the feature and serve the matching Document Policy header:

app.commandLine.appendSwitch(
  'enable-features',
  'DocumentPolicyIncludeJSCallStacksInCrashReports',
);

webContents.on('unresponsive', async () => {
  console.log(await webContents.mainFrame.collectJavaScriptCallStack());
});

Use WebFrameMain.detached for unloading state and isDestroyed() for final destruction. Heap tracing and renderer out-of-memory diagnostics can also capture JavaScript evidence.

Register per-context preloads

Preload registrations can target either frame or service-worker. A service worker preload uses ipcRenderer; communicate from the main process through ServiceWorkerMain.ipc. Use startWorkerForScope() and running-status-changed when lifecycle control is needed.

Filter requests explicitly

const filter = {
  urls: ['<all_urls>'],
  excludeUrls: ['https://example.test/private/*'],
};

Use net.request({ bypassCustomProtocolHandlers: true }) when a request must skip registered protocol handlers. WebSocket authentication arrives through the webContents login event.

Control popups and navigation

webContents.setWindowOpenHandler((details) => ({
  action: 'allow',
  overrideBrowserWindowOptions: {
    resizable: details.features.includes('resizable=yes'),
  },
}));

Set webPreferences.focusOnNavigation to false when navigation must not focus the WebContents. Restore captured history with webContents.navigationHistory.restore(index, entries).

Render frames to PDF

Patch releases add per-frame PDF output:

const frame = browserWindow.webContents.mainFrame;
const pdf = await frame.printToPDF({});

PDF resources render inside the existing WebContents, so detection should inspect the frame tree rather than wait for a guest WebContents.

Work with notifications

• On Windows, use Notification.handleActivation() for clicks, replies, and actions that can cold-start the app.
• Use notification IDs and group IDs for grouping; macOS also exposes history and removal APIs.
• Windows notification actions support buttons, selects, and replies, while the closed event reports a dismissal reason.

Handle graphics predictably

• Shared-texture paint payload fields live beneath handle.
• Imported textures support NV12, NV16, and P010LE; external textures can become VideoFrame objects.
• NativeImage normalizes profiled input to sRGB. Pass a colorSpace option to toBitmap() when source-space output or another conversion is required.
• Use an options object for createFromNamedImage(name, { hslShift }); the positional HSL array is deprecated.

Platform checks

macOS

• Pass WebContents.focusedFrame to Menu.popup({ frame }) for Writing Tools, Autofill, and Services integration.
• Use nativeTheme.shouldUseDarkColorsForSystemIntegratedUI for system UI and shouldDifferentiateWithoutColor for the accessibility preference.
• Configure Touch ID WebAuthn through app.configureWebAuthn() and handle discoverable-account selection on the session.

Linux

• GTK 4 is the GNOME default. Force GTK 3 before startup when native dependencies cannot coexist with GTK 4.
• Frameless windows have rounded corners; disable with roundedCorners: false.
• Window Controls Overlay follows the native title-bar button layout. Position content with env(titlebar-area-x) and env(titlebar-area-width).
• Portal file-dialog backends older than version 4 ignore defaultPath; require portal version 4 when that option is essential.

Windows

• Fullscreen hides the menu bar.
• query-session-end supports pre-shutdown handling, alongside improved session-end behavior.
• roundedCorners is supported, and MSIX applications can use autoUpdater.

Verification checklist

1. Confirm the pinned Electron version and supported operating systems.
2. Search for removed and deprecated APIs before changing dependencies.
3. Test renderer sandbox, preload, protocol, and child-window inheritance.
4. Exercise Wayland/X11, GTK, macOS signing, and Windows packaging paths used by the application.
5. Re-test offscreen scale, image color, media capture, dialogs, notifications, printing, and PDF behavior where applicable.
6. Inspect process-exit reasons and utility-process logs under failure.