imexrps/.ai/electron-main.md

Electron Main, IPC, and Packaging Guide

Main Files

• electron/main.js: Launch shim. Chooses bundled dist-electron/main.cjs in packaged mode when present, otherwise source.
• electron/main-src.js: Source of truth for main process behavior.
• electron/preload.js: Launch shim for preload.
• electron/preload-src.js: Source preload bridge.
• scripts/build-electron.mjs: Builds dist-electron/main.cjs and dist-electron/preload.cjs.

Main Process Responsibilities

electron/main-src.js handles:

• App/window lifecycle.
• Application menu.
• Sentry main process setup.
• Auto-updater and update IPC.
• DevTools configuration.
• Third-party notice window.
• Single-instance locking.
• Tray behavior on minimize.
• Initializing electron-store.
• Loading IPC handlers.
• Dynamic ESM imports for ESM-only Electron packages.

Store Initialization

electron-store v11 is ESM-only. The app uses electron/electron-store.js:

• initializeStore() dynamically imports and creates the store.
• store is a proxy that throws if accessed before initialization.

main-src.js must call:

await initializeStore();
initializeIpcHandlers();

before modules such as analytics, watcher, scanner, audit, or decoder read store.

Store defaults include:

• deviceId
• showChangeLog
• enableNotifications
• filePaths
• accepted_ins_co
• runWatcherOnStartup
• polling
• ins_rule_set

ESM-Only Package Notes

Current major upgrades made these ESM-only:

• electron-context-menu
• electron-store
• electron-is-dev

The app no longer uses electron-is-dev; it uses !app.isPackaged in main and process.defaultApp/process.execPath detection in preload.

Use dynamic import for electron-context-menu:

const { default: contextMenu } = await import("electron-context-menu");

Sentry Electron

Current dependency: @sentry/electron@^7.13.0.

Main process import:

const Sentry = require("@sentry/electron/main");

Renderer import:

import * as Sentry from "@sentry/electron/renderer";

Main setup uses:

ipcMode: Sentry.IPCMode.Protocol

Keep protocol mode unless deliberately changing Sentry IPC behavior. It avoids the deprecated Electron preload path Sentry can otherwise use.

DevTools

Current behavior:

• Dev mode: DevTools enabled and auto-open unless ELECTRON_OPEN_DEVTOOLS=0.
• Packaged mode: DevTools disabled unless ELECTRON_ENABLE_DEVTOOLS=1.
• Packaged auto-open: requires ELECTRON_OPEN_DEVTOOLS=1.
• React DevTools extension installation: opt-in with ELECTRON_INSTALL_REACT_DEVTOOLS=1.

Chrome DevTools can emit Electron backend console noise such as Autofill.enable and Autofill.setAddresses protocol errors. That noise is tied to DevTools/extension behavior, not app runtime failure.

IPC Modules

Shared registration:

• electron/ipc-main-handler.js

Imported modules:

• electron/file-watcher/file-watcher-ipc.js
• electron/file-scan/file-scan-ipc.js
• electron/audit/audit-ipc.js

Avoid importing mainWindow from main-src.js in IPC modules. That caused circular dependency warnings. Use:

const parentWindow = BrowserWindow.fromWebContents(event.sender);

for dialog parents, or BrowserWindow.getAllWindows()[0] for broadcast-style interactions when necessary.

Packaging

package.json contains electron-builder config.

Important scripts:

• npm run build:electron: generates dist-electron/.
• npm run pack: local unpacked package check with --publish never and electron-builder.pack-check.cjs.
• npm run dist: full build/package using package config.
• npm run distp: publishes. Use only when explicitly requested.
• npm run distnopublish: full build/package with publishing disabled.

electron-builder.pack-check.cjs disables Azure Trusted Signing config for pack checks:

azureSignOptions: null

The pack check may still locally sign the unpacked executable with signtool. That is not publishing.

Generated artifacts:

• dist-electron/: bundled main/preload, ignored.
• build/: renderer production build, ignored.
• dist/: electron-builder output, ignored.

Do not manually edit generated artifacts.