moai-framework-electron

# Electron 33+ Desktop Development

## Quick Reference

Electron 33+ Desktop App Development Specialist enables building cross-platform desktop applications with web technologies.

Auto-Triggers: Electron projects detected via electron.vite.config.ts or electron-builder.yml files, desktop app development requests, IPC communication pattern implementation

### Core Capabilities

Electron 33 Platform:

- Chromium 130 rendering engine for modern web features
- Node.js 20.18 runtime for native system access
- Native ESM support in main process
- WebGPU API support for GPU-accelerated graphics

Process Architecture:

- Main process runs as single instance per application with full Node.js access
- Renderer processes display web content in sandboxed environments
- Preload scripts bridge main and renderer with controlled API exposure
- Utility processes handle background tasks without blocking UI

IPC Communication:

- Type-safe invoke/handle patterns for request-response communication
- contextBridge API for secure renderer access to main process functionality
- Event-based messaging for push notifications from main to renderer

Auto-Update Support:

- electron-updater integration with GitHub and S3 publishing
- Differential updates for smaller download sizes
- Update notification and installation management

Packaging Options:

- Electron Forge for integrated build tooling and plugin ecosystem
- electron-builder for flexible multi-platform distribution

Security Features:

- contextIsolation for preventing prototype pollution
- Sandbox enforcement for renderer process isolation
- Content Security Policy configuration
- Input validation patterns for IPC handlers

### Project Initialization

Creating a new Electron application requires running the create-electron-app command with the vite-typescript template. Install electron-builder as a development dependency for packaging. Add electron-updater as a runtime dependency for auto-update functionality.

For detailed commands and configuration, see reference.md Quick Commands section.

---

## Implementation Guide

### Project Structure

Recommended Directory Layout:

The source directory should contain four main subdirectories:

Main Directory: Contains the main process entry point, IPC handler definitions organized by domain, business logic services, and window management modules

Preload Directory: Contains the preload script entry point and exposed API definitions that bridge main and renderer

Renderer Directory: Contains the web application built with React, Vue, or Svelte, including the HTML entry point and Vite configuration

Shared Directory: Contains TypeScript types and constants shared between main and renderer processes

The project root should include the electron.vite.config.ts for build configuration, electron-builder.yml for packaging options, and resources directory for app icons and assets.

### Main Process Setup

Application Lifecycle Management:

The main process initialization follows a specific sequence. First, enable sandbox globally using app.enableSandbox() to ensure all renderer processes run in isolated environments. Then request single instance lock to prevent multiple app instances from running simultaneously.

Window creation should occur after the app ready event fires. Configure BrowserWindow with security-focused webPreferences including contextIsolation enabled, nodeIntegration disabled, sandbox enabled, and webSecurity enabled. Set the preload script path to expose safe APIs to the renderer.

Handle platform-specific behaviors: on macOS, re-create windows when the dock icon is clicked if no windows exist. On other platforms, quit the application when all windows close.

For implementation examples, see examples.md Main Process Entry Point section.

### Type-Safe IPC Communication

IPC Type Definition Pattern:

Define an interface that maps channel names to their payload types. Group channels by domain such as file operations, window operations, and storage operations. This enables type checking for both main process handlers and renderer invocations.

Main Process Handler Registration:

Register IPC handlers in a dedicated module that imports from the shared types. Each handler should validate input using a schema validation library such as Zod before processing. Use ipcMain.handle for request-response patterns and return structured results.

Preload Script Implementation:

Create an API object that wraps ipcRenderer.invoke calls for each channel. Use contextBridge.exposeInMainWorld to make this API available in the renderer as window.electronAPI. Include cleanup functions for event listeners to prevent memory leaks.

For complete IPC implementation patterns, see examples.md Type-Safe IPC Implementation section.

### Security Best Practices

Mandatory Security Settings:

Every BrowserWindow must have webPreferences configured with four critical settings. contextIsolation must always be enabled to prevent renderer code from accessing Electron internals. nodeIntegration must always be disabled in renderer processes. sandbox must always be enabled for process-level isolation. webSecurity must never be disabled to maintain same-origin policy enforcement.

Content Security Policy:

Configure session-level CSP headers using webRequest.onHeadersReceived. Restrict default-src to self, script-src to self without unsafe-inline, and connect-src to allowed API domains. This prevents XSS attacks and unauthorized resource loading.

Input Validation:

Every IPC handler must validate inputs before processing. Prevent path traversal attacks by rejecting paths containing parent directory references. Validate file names against reserved characters. Use allowlists for permitted directories when implementing file access.

For security implementation details, see reference.md Security Best Practices section.

### Auto-Update Implementation

Update Service Architecture:

Create an UpdateService class that manages the electron-update