Electron

Common errors

• Error: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()

  cause Attempting to `require()` an ES Module (ESM) in a CommonJS context, typically in the main process.
  fix For an ESM module, use `import()` dynamically or ensure your main process entry file is an ES Module (e.g., `"type": "module"` in `package.json` and use `.mjs` extension) to use top-level `import` statements. Or, find a CommonJS compatible version of the dependency.

• Uncaught ReferenceError: require is not defined

  cause Attempting to use `require()` in a renderer process where `nodeIntegration` is `false` (which is the secure default).
  fix Access Node.js APIs and other main process functionalities securely via a preload script with `contextIsolation: true`. Expose necessary functions from the preload script to the renderer's `window` object, or use `ipcRenderer` to communicate with the main process.

• Cannot read properties of undefined (reading 'send') or 'invoke')

  cause Trying to use `ipcRenderer.send` or `ipcRenderer.invoke` in the renderer process, but the `ipcRenderer` object is not available or properly exposed due to `contextIsolation`.
  fix Ensure `contextIsolation: true` is set in `webPreferences`. In your `preload.js` script, use `contextBridge.exposeInMainWorld` to selectively expose an API to the renderer process, which then uses `window.myAPI.send(...)` or `window.myAPI.invoke(...)`.

Warnings

• breaking Electron's core APIs (like `BrowserWindow`, `Menu`, etc.) often have breaking changes between major versions due to Chromium and Node.js updates, or refactoring for security and stability. Always consult the migration guide for each major version upgrade.
  Fix: Review the official Electron release notes and migration guides for your target major version. Pay close attention to changes in `webPreferences` and security defaults.
• breaking The default values for `nodeIntegration` and `contextIsolation` in `webPreferences` have changed over time and are now `false` and `true` respectively by default. Disabling `nodeIntegration` and enabling `contextIsolation` is a critical security hardening measure.
  Fix: Explicitly set `nodeIntegration: false` and `contextIsolation: true` in your `BrowserWindow`'s `webPreferences` for all new projects and consider migrating existing ones. Use preload scripts and IPC for communication between renderer and main processes.
• gotcha Electron's `remote` module was deprecated and eventually removed to improve security and maintainability. Direct access to main process modules from the renderer process is no longer supported.
  Fix: Migrate away from the `remote` module. Instead, use secure patterns like IPC (Inter-Process Communication) via `ipcRenderer` and `ipcMain`, often facilitated by a sandboxed preload script, to expose necessary main process functionalities to the renderer.
• deprecated Many Electron APIs, especially those related to deprecated Chromium features or security vulnerabilities, may become deprecated or removed without a full major version bump, typically with a warning in the console.
  Fix: Regularly check the official Electron documentation and release notes. Monitor your application's console for deprecation warnings during development and testing, and update your code accordingly.
• gotcha Packaging and distributing Electron applications can be complex, especially with native modules. Misconfiguration of `electron-builder` or `electron-packager` can lead to broken builds or platform-specific issues.
  Fix: Use official tools like `electron-builder` or `electron-packager`. Ensure native modules are rebuilt for Electron's specific Node.js version and architecture. Test builds thoroughly on all target platforms.

Install

• npm install electron npm
• yarn add electron yarn
• pnpm add electron pnpm

Imports

• app
  wrong:

  const { app, BrowserWindow } = require('electron')

  correct:

  import { app, BrowserWindow } from 'electron'

  While CommonJS `require` is still widely used in the main process, ESM `import` is increasingly preferred for modern Electron development, especially in type-aware environments. Both work in the main process.
• BrowserWindow
  wrong:

  import BrowserWindow from 'electron'

  correct:

  import { BrowserWindow } from 'electron'

  `BrowserWindow` is a named export, not a default export. Always destructure it.
• ipcRenderer

  import { ipcRenderer } from 'electron'

  `ipcRenderer` is typically imported in the renderer process or preload scripts to communicate with the main process. Ensure `contextIsolation` is properly configured for security.
• globalShortcut

  import { globalShortcut } from 'electron'

  `globalShortcut` is available only in the main process for registering system-wide keyboard shortcuts.

Quickstart

This quickstart initializes an Electron application, creates a main window, loads an HTML file, and sets up basic lifecycle events. It emphasizes best practices for `webPreferences` like `nodeIntegration: false` and `contextIsolation: true` for enhanced security.

import { app, BrowserWindow } from 'electron';
import path from 'path';

const createWindow = () => {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      nodeIntegration: false, // Strongly recommended to be false for security
      contextIsolation: true // Strongly recommended to be true for security
    }
  });

  mainWindow.loadFile('index.html');
  // Open the DevTools.
  // mainWindow.webContents.openDevTools();
};

app.whenReady().then(() => {
  createWindow();

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow();
  });
});

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit();
});