153 lines
4.1 KiB
Markdown
153 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```js
|
|
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`:
|
|
|
|
```js
|
|
const { default: contextMenu } = await import("electron-context-menu");
|
|
```
|
|
|
|
## Sentry Electron
|
|
|
|
Current dependency: `@sentry/electron@^7.13.0`.
|
|
|
|
Main process import:
|
|
|
|
```js
|
|
const Sentry = require("@sentry/electron/main");
|
|
```
|
|
|
|
Renderer import:
|
|
|
|
```js
|
|
import * as Sentry from "@sentry/electron/renderer";
|
|
```
|
|
|
|
Main setup uses:
|
|
|
|
```js
|
|
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:
|
|
|
|
```js
|
|
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:
|
|
|
|
```js
|
|
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.
|
|
|