d-subrahmanyam/electron

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