electron

Electron Best Practices

Electron development demands a disciplined approach to security, performance, and maintainability. This guide outlines the definitive best practices for our team, leveraging modern Electron features and tooling (targeting Electron 28+).

1. Project Setup & Structure

Always start with Electron Forge to standardize project structure, build pipelines, and stay aligned with the latest Electron APIs.

• Scaffolding: Use a modern template like Vite + TypeScript. ❌ BAD: Manual setup, outdated CLIs. ✅ GOOD:

  npx create-electron-app@latest my-app --template=vite-typescript
  

• File Naming: Adhere to Electron's coding style for JavaScript files. ❌ BAD: my_module.js ✅ GOOD: my-module.js

2. Security Fundamentals (Non-Negotiable)

Security is paramount. Always enable context isolation and expose APIs safely.

• Context Isolation (Mandatory): Keep contextIsolation enabled. It's on by default since Electron 12. ❌ BAD: new BrowserWindow({ webPreferences: { contextIsolation: false } }) ✅ GOOD: (Default behavior, no explicit setting needed unless overriding)

  // main.mjs
  new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.mjs'),
      sandbox: true // Strongly recommended
    }
  })
  

• Safe API Exposure with contextBridge: Never mutate the global window object directly. Use contextBridge.exposeInMainWorld and filter arguments. ❌ BAD: Exposing ipcRenderer.send directly.

  // preload.mjs
  const { contextBridge, ipcRenderer } = require('electron');
  contextBridge.exposeInMainWorld('myAPI', {
    send: ipcRenderer.send // ❌ Allows renderer to send arbitrary IPC messages
  });
  

  ✅ GOOD: Expose specific, argument-filtered functions.

  // preload.mjs
  import { contextBridge, ipcRenderer } from 'electron';
  
  contextBridge.exposeInMainWorld('electronAPI', {
    loadPreferences: () => ipcRenderer.invoke('load-prefs'),
    saveSettings: (settings) => {
      // ✅ Validate and filter arguments before sending
      if (typeof settings === 'object' && settings !== null) {
        ipcRenderer.send('save-settings', settings);
      } else {
        console.error('Invalid settings object provided.');
      }
    }
  });
  
  // interface.d.ts (for TypeScript)
  declare global {
    interface Window {
      electronAPI: {
        loadPreferences: () => Promise<any>;
        saveSettings: (settings: object) => void;
      };
    }
  }