🖥️ Electron Complete Guide

{
  "name": "memo-app",
  "productName": "Memo",
  "version": "1.0.0",
  "description": "Electron guide example",
  "type": "module",
  "main": "src/main.js",
  "scripts": {
    "start": "electron .",
    "test": "node --test"
  },
  "devDependencies": {
    "electron": "^44.5.1"
  }
}

import { app, BrowserWindow, ipcMain, shell } from 'electron';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';
import { createNotesStore } from './notes-store.js';

const RENDERER_DIR = join(import.meta.dirname, 'renderer');
const RENDERER_URL = pathToFileURL(join(RENDERER_DIR, 'index.html')).href;

let store;

function createWindow() {
  const win = new BrowserWindow({
    width: 900,
    height: 640,
    show: false,
    webPreferences: {
      preload: join(import.meta.dirname, 'preload.cjs'),
      // These three are the defaults, stated explicitly so they are not changed by mistake
      contextIsolation: true,
      sandbox: true,
      nodeIntegration: false,
    },
  });

  // Showing the window after the page is ready avoids a white flash
  win.once('ready-to-show', () => win.show());

  // Do not let the app navigate to another address
  win.webContents.on('will-navigate', (event, url) => {
    if (url !== RENDERER_URL) event.preventDefault();
  });

  // Never create new windows; open only https links in the default browser
  win.webContents.setWindowOpenHandler(({ url }) => {
    if (url.startsWith('https://')) shell.openExternal(url);
    return { action: 'deny' };
  });

  win.loadFile(join(RENDERER_DIR, 'index.html'));
  return win;
}

// (the IPC registration code is added in the next section)

app.whenReady().then(() => {
  store = createNotesStore(join(app.getPath('userData'), 'notes.json'));
  registerIpc();
  createWindow();

  // macOS: recreate the window when the Dock icon is clicked and none is open
  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow();
  });
});

// Windows · Linux: quit the app when every window is closed
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit();
});

// Check that the page sending the request is our own page
function assertTrustedSender(event) {
  if (event.senderFrame?.url !== RENDERER_URL) throw new Error('Request not allowed');
}

function registerIpc() {
  ipcMain.handle('notes:list', (event) => {
    assertTrustedSender(event);
    return store.list();
  });
  ipcMain.handle('notes:add', (event, input) => {
    assertTrustedSender(event);
    return store.add(input);      // input is validated inside store.add
  });
  ipcMain.handle('notes:remove', (event, id) => {
    assertTrustedSender(event);
    if (typeof id !== 'string') throw new TypeError('Invalid id');
    return store.remove(id);
  });
}

const { contextBridge, ipcRenderer } = require('electron');

// Expose only the functions the page (renderer) needs, each under a name.
// Handing over ipcRenderer itself would let page code call any channel.
contextBridge.exposeInMainWorld('notes', {
  list: () => ipcRenderer.invoke('notes:list'),
  add: (note) => ipcRenderer.invoke('notes:add', note),
  remove: (id) => ipcRenderer.invoke('notes:remove', id),
});

// main.js — tell the page when a menu item is clicked
win.webContents.send('menu:new-note');

// preload.cjs — wrap it in a function so the page can receive the notification
contextBridge.exposeInMainWorld('appEvents', {
  onNewNote: (callback) => ipcRenderer.on('menu:new-note', () => callback()),
});

// renderer.js
window.appEvents.onNewNote(() => document.querySelector('#title').focus());

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self'">
  <title>Memo</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <form id="form">
    <input id="title" placeholder="Title" maxlength="100" required>
    <textarea id="body" placeholder="Body"></textarea>
    <button>Save</button>
  </form>
  <p id="error" role="alert"></p>
  <ul id="list"></ul>
  <script src="renderer.js"></script>
</body>
</html>

const form = document.querySelector('#form');
const list = document.querySelector('#list');
const error = document.querySelector('#error');

async function render() {
  const notes = await window.notes.list();
  list.replaceChildren(...notes.map((note) => {
    const item = document.createElement('li');
    item.textContent = note.title;          // textContent, not innerHTML: input is not interpreted as HTML
    const remove = document.createElement('button');
    remove.textContent = 'Delete';
    remove.addEventListener('click', async () => {
      await window.notes.remove(note.id);
      render();
    });
    item.append(' ', remove);
    return item;
  }));
}

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  error.textContent = '';
  try {
    await window.notes.add({
      title: document.querySelector('#title').value,
      body: document.querySelector('#body').value,
    });
    form.reset();
    render();
  } catch (err) {
    error.textContent = err.message;
  }
});

render();

new BrowserWindow({
  webPreferences: {
    nodeIntegration: true,      // the page can require('child_process') → forbidden
    contextIsolation: false,    // the page can tamper with preload's objects → forbidden
    sandbox: false,             // removes the renderer's isolation → forbidden
    webSecurity: false,         // removes the same-origin policy → forbidden
  },
});

// Exposing the whole ipcRenderer from preload is also forbidden
contextBridge.exposeInMainWorld('ipc', ipcRenderer);

import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
import { dirname } from 'node:path';

const MAX_TITLE = 100;
const MAX_BODY = 10_000;

// Values from the page are not trusted: check shape and length before saving
export function validateNote(input) {
  if (typeof input !== 'object' || input === null) throw new TypeError('Invalid note format');
  const title = typeof input.title === 'string' ? input.title.trim() : '';
  const body = typeof input.body === 'string' ? input.body : '';
  if (!title) throw new TypeError('Enter a title');
  if (title.length > MAX_TITLE) throw new TypeError(`The title must be at most ${MAX_TITLE} characters`);
  if (body.length > MAX_BODY) throw new TypeError(`The body must be at most ${MAX_BODY} characters`);
  return { title, body };
}

export function createNotesStore(filePath) {
  async function readAll() {
    try {
      return JSON.parse(await readFile(filePath, 'utf8'));
    } catch (err) {
      if (err.code === 'ENOENT') return [];   // first run: the file does not exist yet
      throw err;
    }
  }

  async function writeAll(notes) {
    await mkdir(dirname(filePath), { recursive: true });
    // Write to a temporary file, then rename: the existing file is not corrupted if the app quits mid-write
    const tmp = `${filePath}.tmp`;
    await writeFile(tmp, JSON.stringify(notes, null, 2));
    await rename(tmp, filePath);
  }

  return {
    list: readAll,
    async add(input) {
      const note = { id: crypto.randomUUID(), ...validateNote(input), createdAt: new Date().toISOString() };
      const notes = await readAll();
      notes.unshift(note);
      await writeAll(notes);
      return note;
    },
    async remove(id) {
      const notes = await readAll();
      await writeAll(notes.filter((note) => note.id !== id));
    },
  };
}

import { Menu } from 'electron';

const menu = Menu.buildFromTemplate([
  {
    label: 'File',
    submenu: [
      { label: 'New Memo', accelerator: 'CmdOrCtrl+N', click: () => win.webContents.send('menu:new-note') },
      { type: 'separator' },
      { role: 'quit', label: 'Quit' },
    ],
  },
  {
    label: 'Edit',
    submenu: [{ role: 'undo' }, { role: 'redo' }, { type: 'separator' }, { role: 'cut' }, { role: 'copy' }, { role: 'paste' }],
  },
  {
    label: 'View',
    submenu: [{ role: 'reload' }, { role: 'toggleDevTools' }],
  },
]);
Menu.setApplicationMenu(menu);

import { dialog } from 'electron';
import { readFile } from 'node:fs/promises';

ipcMain.handle('file:import', async (event) => {
  assertTrustedSender(event);
  const { canceled, filePaths } = await dialog.showOpenDialog({
    title: 'Choose a memo to import',
    properties: ['openFile'],
    filters: [{ name: 'Text', extensions: ['txt', 'md'] }],
  });
  if (canceled) return null;

  // Use only the path the user picked in the dialog (the page never sends a path)
  return { name: filePaths[0], text: await readFile(filePaths[0], 'utf8') };
});

import { Tray, Menu, Notification, nativeImage } from 'electron';

let tray;   // as a local variable it would be garbage collected and the icon would disappear

function createTray(win) {
  tray = new Tray(nativeImage.createFromPath(join(import.meta.dirname, 'tray.png')));
  tray.setToolTip('Memo');
  tray.setContextMenu(Menu.buildFromTemplate([
    { label: 'Open', click: () => win.show() },
    { role: 'quit', label: 'Quit' },
  ]));
}

new Notification({ title: 'Memo', body: 'Memo saved' }).show();

// app.isPackaged is true in a packaged app
if (!app.isPackaged) {
  win.webContents.openDevTools({ mode: 'detach' });
}

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { createNotesStore, validateNote } from '../src/notes-store.js';

test('a saved memo appears first in the list', async (t) => {
  const dir = await mkdtemp(join(tmpdir(), 'memo-'));
  t.after(() => rm(dir, { recursive: true, force: true }));
  const store = createNotesStore(join(dir, 'notes.json'));

  assert.deepEqual(await store.list(), []);
  await store.add({ title: 'First memo', body: '' });
  const second = await store.add({ title: '  Second memo  ', body: 'Body' });

  const notes = await store.list();
  assert.equal(notes.length, 2);
  assert.equal(notes[0].title, 'Second memo');

  await store.remove(second.id);
  assert.equal((await store.list()).length, 1);
});

test('rejects a missing title or a wrong format', () => {
  assert.throws(() => validateNote({ title: '   ' }), /Enter a title/);
  assert.throws(() => validateNote('a string'), /Invalid note format/);
  assert.throws(() => validateNote({ title: 'a'.repeat(101) }), /at most 100 characters/);
});

// npm install --save-dev @playwright/test
import { test, expect, _electron as electron } from '@playwright/test';

test('an added memo shows up in the list', async () => {
  const app = await electron.launch({ args: ['.'] });
  const page = await app.firstWindow();

  await page.fill('#title', 'E2E memo');
  await page.click('button');
  await expect(page.locator('#list li')).toContainText('E2E memo');

  await app.close();
});

export default {
  packagerConfig: {
    asar: true,                    // bundle the app source into a single app.asar file
    ignore: [/^\/test($|\/)/],     // paths to leave out of the package
  },
  makers: [
    { name: '@electron-forge/maker-zip' },
  ],
};

{
  "scripts": {
    "start": "electron-forge start",
    "package": "electron-forge package",
    "make": "electron-forge make",
    "test": "node --test"
  }
}

import { autoUpdater, dialog } from 'electron';

// Works only in a packaged app
if (app.isPackaged) {
  autoUpdater.setFeedURL({ url: 'https://updates.example.com/memo/' + process.platform + '/' + app.getVersion() });

  autoUpdater.on('update-downloaded', async () => {
    const { response } = await dialog.showMessageBox({
      message: 'A new version has been downloaded. Restart now?',
      buttons: ['Restart', 'Later'],
    });
    if (response === 0) autoUpdater.quitAndInstall();
  });

  autoUpdater.checkForUpdates();
}