Electron — Desktop Applications Reference

1
2
3
4
5
6
7
8

main process                    renderer (per window)
------------------------------  ------------------------------
app, BrowserWindow, Menu        DOM, CSS, React/Angular
dialog, tray, notifications     fetch(), workers
fs, child_process, ipcMain      ipcRenderer (through preload)
                                
nodeIntegration: false          -> renderer has NO Node access
contextIsolation: true          -> isolated JS world for the page

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// package.json
{
  "main": "dist/main/index.js",
  "scripts": {
    "dev": "electron-vite dev",
    "build": "electron-vite build",
    "package": "electron-builder --dir",
    "dist": "electron-vite build && electron-builder"
  },
  "devDependencies": {
    "electron": "^31.0.0",
    "electron-vite": "^2.3.0",
    "electron-builder": "^24.13.0"
  }
}

// electron.vite.config.ts
export default defineConfig({
  main:    { build: { outDir: 'dist/main' } },
  preload: { build: { outDir: 'dist/preload' } },
  renderer:{ build: { outDir: 'dist/renderer' } }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

const gotLock = app.requestSingleInstanceLock();
if (!gotLock) { app.quit(); }
else {
  app.on('second-instance', () => {
    const win = BrowserWindow.getAllWindows()[0];
    if (win) { if (win.isMinimized()) { win.restore(); } win.focus(); }
  });

  app.whenReady().then(() => {
    createWindow();                     // new BrowserWindow({ ... })
    app.on('activate', () => {          // macOS dock click
      if (BrowserWindow.getAllWindows().length === 0) { createWindow(); }
    });
  });

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

const api = {
  loadSettings: () => ipcRenderer.invoke('settings:load'),
  saveSettings: (s: Settings) => ipcRenderer.invoke('settings:save', s),
  onSyncStatus: (cb: (s: SyncStatus) => void) => {
    const listener = (_e: unknown, s: SyncStatus) => cb(s);
    ipcRenderer.on('sync:status', listener);
    return () => ipcRenderer.removeListener('sync:status', listener);
  }
};

contextBridge.exposeInMainWorld('desktop', api);

// renderer: window.desktop.saveSettings({ theme: 'dark' })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// main/ipc.ts
ipcMain.handle('files:open', async (_event, args: unknown) => {
  const { filters } = OpenDialogSchema.parse(args);      // zod validation
  const result = await dialog.showOpenDialog({ properties: ['openFile'], filters });
  if (result.canceled || result.filePaths.length === 0) { return null; }
  return fs.promises.readFile(result.filePaths[0], 'utf8');
});

// long job with progress
ipcMain.handle('export:run', async (event, jobId: string) => {
  for (let pct = 0; pct <= 100; pct += 10) {
    await work(pct);
    event.sender.send('export:progress', { jobId, pct });   // push to that window
  }
  return { ok: true };
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

const win = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, '../preload/index.js'),
    contextIsolation: true,     // default true; never turn it off
    nodeIntegration: false,     // renderer gets no require()
    sandbox: true,              // renderer in the OS sandbox
    webSecurity: true
  }
});

// Only your own origin may navigate or open windows
win.webContents.on('will-navigate', (e, url) => {
  if (new URL(url).origin !== APP_ORIGIN) { e.preventDefault(); }
});
win.webContents.setWindowOpenHandler(({ url }) => {
  shell.openExternal(url);
  return { action: 'deny' };
});

// CSP delivered with the document (index.html meta or headers)
// default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// Tray + notification
const tray = new Tray(path.join(__dirname, 'icon.png'));
tray.setToolTip('Orders desktop');
tray.on('click', () => mainWindow.show());
tray.setContextMenu(Menu.buildFromTemplate([
  { label: 'Open', click: () => mainWindow.show() },
  { label: 'Quit', role: 'quit' }
]));

new Notification({
  title: 'Sync finished',
  body: `${count} orders imported`
}).show();

// Always resolve paths through app.getPath
const logsDir = app.getPath('logs');    // userData, downloads, documents...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// electron-builder.yml
appId: com.example.orders
productName: Orders
directories: { output: release, buildResources: build }
files:
  - dist/**
  - package.json
asar: true
asarUnpack:
  - "**/*.node"
win:
  target: [nsis]
  signingHashAlgorithms: [sha256]
mac:
  target: [dmg, zip]
  hardenedRuntime: true
  entitlements: build/entitlements.mac.plist
linux:
  target: [AppImage, deb]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

import { autoUpdater } from 'electron-updater';

autoUpdater.channel = app.isPackaged ? 'stable' : 'beta';
autoUpdater.autoDownload = true;
autoUpdater.autoInstallOnAppQuit = true;

autoUpdater.on('update-available', i => log.info('update available', i.version));
autoUpdater.on('error', e => log.error('update failed', e));

app.whenReady().then(async () => {
  if (!app.isPackaged) { return; }        // never update in development
  await autoUpdater.checkForUpdatesAndNotify();
});

// Never auto-restart while the user has unsaved work: prompt instead

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// 1. Create the window early, show it late
const win = new BrowserWindow({ show: false, backgroundColor: '#ffffff' });
win.once('ready-to-show', () => win.show());

// 2. Defer non-critical initialisation
app.whenReady().then(async () => {
  createWindow();
  setTimeout(() => warmUpCaches(), 3000);   // after the UI is visible
});

// 3. Keep payloads small across the bridge
//    structured clone on every IPC call: send ids, not whole collections

// 4. Measure instead of guessing
//    app.commandLine.appendSwitch('enable-logging')
//    DevTools > Performance, and `--inspect` for the main process

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import { test, expect, _electron as electron } from '@playwright/test';

test('opens a document and shows it in the editor', async () => {
  const app = await electron.launch({ args: ['.'] });
  const window = await app.firstWindow();

  await window.getByRole('button', { name: 'Open file' }).click();
  await expect(window.getByRole('textbox')).toHaveValue(/invoice/);

  const title = await app.evaluate(({ app }) => app.getVersion());
  expect(title).toBe('1.4.0');
  await app.close();
});

// Unit level: the preload API surface, with ipcRenderer mocked
vi.mock('electron', () => ({ ipcRenderer: { invoke: vi.fn() } }));

1
2
3
4
5
6
7
8
9
10
11
12
13

import { crashReporter } from 'electron';
import log from 'electron-log';

crashReporter.start({ productName: 'Orders', uploadToServer: false });
log.transports.file.resolvePathFn = () => path.join(app.getPath('logs'), 'main.log');
log.transports.file.maxSize = 5 * 1024 * 1024;

process.on('uncaughtException', e => log.error('uncaught', e));

app.on('render-process-gone', (_e, _wc, details) =>
  log.error('renderer gone', details.reason));

// Ship source maps separately so `frame` maps back to your TypeScript

1
2
3
4
5

// Decision in three questions:
// 1. Does it need file system, devices or long-running local work?  no  -> PWA
// 2. Is it Windows-only with a .NET team?                            yes -> WPF/WinUI
// 3. Is binary size or memory the hard constraint?                    yes -> Tauri
// Otherwise: Electron, and reuse the web team's stack.