moai-framework-electron

Define a shared TypeScript interface mapping channel names to payload types, register handlers in the main process with ipcMain.handle, and expose wrapped ipcRenderer.invoke calls through contextBridge.exposeInMainWorld in the preload script. Validate all inputs with Zod before processing.

Create an UpdateService class that initializes electron-updater with a reference to the main window, set autoDownload to false for user control, and handle update-available, download-progress, and update-downloaded events. The app must be code-signed and publish configuration must be set in electron-builder.yml.

Electron Forge provides integrated build tooling with a plugin ecosystem including Vite support and GitHub publishers. electron-builder offers flexible multi-platform targets like NSIS, DMG, AppImage, deb, and rpm with detailed signing and notarization options.

Every BrowserWindow must set contextIsolation to true, nodeIntegration to false, sandbox to true, and webSecurity to true. Additionally configure Content Security Policy headers via session.webRequest.onHeadersReceived and validate all IPC inputs to prevent path traversal.

White screens usually come from an incorrect preload script path relative to the build output, loadFile or loadURL pointing to missing files, or CSP rules blocking script execution. Open DevTools to inspect console errors and verify paths.

Native modules are compiled against the system Node.js version by default, but Electron embeds its own Node.js runtime. Run npx electron-rebuild after npm install, or add it as a postinstall script to automate recompilation.