Electron Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: electron for comprehensive API documentation.

When NOT to Use This Skill

• Tauri applications - Use the tauri skill for Rust-based desktop apps
• Web applications only - Electron is for desktop apps, not web deployment
• Mobile applications - Electron doesn't support iOS/Android natively
• CLI tools - Use Node.js directly for command-line applications

---

Architecture

Process Model

┌─────────────────────────────────────────────────────────────┐
│                      Main Process                           │
│  - Node.js Runtime (full access)                            │
│  - Electron APIs (app, BrowserWindow, ipcMain, dialog)      │
└──────────────────────────┬──────────────────────────────────┘
                           │ IPC Channel
┌──────────────────────────▼──────────────────────────────────┐
│                    Preload Script                           │
│  - Executes before renderer                                 │
│  - Uses contextBridge to expose safe APIs                   │
└──────────────────────────┬──────────────────────────────────┘
                           │ contextBridge.exposeInMainWorld()
┌──────────────────────────▼──────────────────────────────────┐
│                   Renderer Process                          │
│  - Chromium Runtime (standard Web APIs)                     │
│  - No direct Node.js access (by default)                    │
│  - window.electronAPI (exposed via preload)                 │
└─────────────────────────────────────────────────────────────┘

Project Structure

electron-app/
├── src/
│   ├── main/                    # Main process
│   │   ├── index.ts             # Entry point
│   │   ├── window.ts            # Window management
│   │   ├── ipc/                 # IPC handlers
│   │   └── updater.ts           # Auto-updates
│   ├── preload/
│   │   ├── index.ts             # Main preload
│   │   └── types.d.ts           # Type declarations
│   └── renderer/                # Frontend app
├── resources/                   # App icons
├── electron-builder.yml         # Packaging config
└── package.json

---

IPC Communication Essentials

Preload Script

// src/preload/index.ts
import { contextBridge, ipcRenderer } from 'electron';

const electronAPI = {
  openFile: () => ipcRenderer.invoke('dialog:openFile'),
  saveFile: (content: string) => ipcRenderer.invoke('dialog:saveFile', content),
  getVersion: () => ipcRenderer.invoke('app:getVersion'),
};

contextBridge.exposeInMainWorld('electronAPI', electronAPI);

// Event subscriptions
contextBridge.exposeInMainWorld('electronEvents', {
  onMenuAction: (callback: (action: string) => void) => {
    const handler = (_e: any, action: string) => callback(action);
    ipcRenderer.on('menu:action', handler);
    return () => ipcRenderer.removeListener('menu:action', handler);
  },
});

Main Process Handlers

// src/main/ipc/index.ts
import { ipcMain, dialog, app } from 'electron';

export function registerIpcHandlers() {
  ipcMain.handle('dialog:openFile', async () => {
    const result = await dialog.showOpenDialog({
      properties: ['openFile'],
    });
    return result.canceled ? null : result.filePaths[0];
  });

  ipcMain.handle('app:getVersion', () => app.getVersion());
}

Full Reference: See ipc-security.md for complete IPC patterns and type-safe setup.

---

Security Essentials

Secure BrowserWindow

const win = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, 'preload.js'),
    contextIsolation: true,      // REQUIRED
    nodeIntegration: false,      // REQUIRED
    sandbox: true,               // Recommended
    webSecurity: true,           // NEVER disable
  },
});

// Content Security Policy
win.webContents.session.webRequest.onHeadersReceived((details, callback) => {
  callback({
    responseHeaders: {
      ...details.responseHeaders,
      'Content-Security-Policy': [
        "default-src 'self'",
        "script-src 'self'",
        "connect-src 'self' https://api.example.com",
      ].join('; '),
    },
  });
});

Security Checklist

• contextIsolation: true - Isolate preload from renderer
• nodeIntegration: false - No Node.js APIs in renderer
• sandbox: true - OS-level process sandboxing
• Never expose raw ipcRenderer to renderer
• Validate ALL inputs in ipcMain.handle() handlers
• Use safeStorage API for credentials

Full Reference: See ipc-security.md for complete security configuration.

---

Packaging Quick Start

Electron Builder (electron-builder.yml)

appId: com.company.app
productName: My Application

mac:
  hardenedRuntime: true
  target: [dmg, zip]

win:
  target: [nsis, portable]

linux:
  target: [AppImage, deb]

publish:
  provider: github
  owner: company
  repo: app

Auto-Updates

import { autoUpdater } from 'electron-updater';

autoUpdater.on('update-available', (info) => {
  dialog.showMessageBox({
    message: `Version ${info.version} available`,
    buttons: ['Download', 'Later'],
  }).then(({ response }) => {
    if (response === 0) autoUpdater.downloadUpdate();
  });
});

autoUpdater.on('update-downloaded', () => {
  autoUpdater.quitAndInstall();
});

// Check on startup
autoUpdater.checkForUpdates();

Full Reference: See packaging.md for complete Forge and Builder configuration.

---

Backend Integration

Local SQLite Database

import Database from 'better-sqlite3';
import { app } from 'electron';

const db = new Database(path.join(app.getPath('userData'), 'app.db'));
db.pragma('journal_mode = WAL');

export const itemsRepo = {
  getAll: () => db.prepare('SELECT * FROM items').all(),
  create: (data) => db.prepare('INSERT INTO items (name) VALUES (?)').run(data.name),
};

Secure Token Storage

import { safeStorage } from 'electron';
import Store from 'electron-store';

const store = new Store({ name: 'auth' });

export const tokenStore = {
  setToken(token: string): void {
    if (safeStorage.isEncryptionAvailable()) {
      const encrypted = safeStorage.encryptString(token);
      store.set('accessToken', encrypted.toString('base64'));
    }
  },
  getToken(): string | null {
    const stored = store.get('accessToken') as string;
    if (safeStorage.isEncryptionAvailable()) {
      return safeStorage.decryptString(Buffer.from(stored, 'base64'));
    }
    return stored;
  },
};

Full Reference: See backend.md for embedded servers, offline-first patterns, and WebSocket integration.

---

Production Checklist

Build & Packaging

• Code signing configured for all platforms
• macOS notarization enabled
• ASAR packaging enabled

Security

• All security defaults enforced
• CSP headers configured
• IPC handlers validate all inputs
• safeStorage used for credentials

Performance

• Startup time < 3 seconds
• Memory usage baseline established

Monitoring Metrics

Metric	Warning	Critical
Startup time	> 3s	> 5s
Memory usage	> 300MB	> 500MB
Crash rate	> 0.1%	> 1%

---

Anti-Patterns

Anti-Pattern	Problem	Solution
nodeIntegration: true	Major security risk	Use contextIsolation: true + preload
webSecurity: false	Enables XSS	Never disable
Exposing raw ipcRenderer	Security hole	Use contextBridge.exposeInMainWorld()
No input validation	Injection attacks	Validate in ipcMain.handle()
Hardcoded credentials	Exposed in ASAR	Use safeStorage API
ipcRenderer.sendSync	Blocks renderer	Use async invoke()

---

Quick Troubleshooting

Issue	Solution
require is not defined	Use preload with contextBridge
IPC returns undefined	Verify channel names match
White screen on startup	Check DevTools console
Auto-updater not checking	Ensure app is code-signed
High memory usage	Check for unbounded caches
App won't start on macOS	Complete notarization

---

Reference Files

File	Content
ipc-security.md	Type-safe IPC, Security configuration
packaging.md	Electron Forge, Builder, Auto-updates
backend.md	SQLite, Express, Offline-first, WebSocket

---

External Documentation

• Electron Official Docs
• Electron Security
• Electron Forge
• electron-builder