Getting Started

Getting Started with Electron

Overview

Electron builds cross-platform desktop apps (macOS, Windows, Linux) with HTML/CSS/JS by combining Chromium for the UI and Node.js for system access. Mental model: one main process (Node.js, controls lifecycle and windows) drives many renderer processes (web pages, no Node by default), and a preload script safely bridges the two.

When to use

• Scaffolding a brand-new Electron app from an empty folder.
• You need the minimal runnable skeleton: package.json main, main.js, index.html, optional preload.js.
• Clarifying the main/renderer/preload split before writing real features.
• You hit a blank window, "app is not ready", or require is not defined in the page.

When NOT to use: deep IPC patterns → process-model-ipc; window options → windows; security hardening → security; building installers → distribution.

Quick reference

| API | Purpose | |---|---| | package.json "main" | Entry script = the main process; defaults to index.js | | app.whenReady() | Promise; create windows only after it resolves | | new BrowserWindow(opts) | Open a window; width/height/webPreferences.preload | | win.loadFile('index.html') | Load a local HTML file into the renderer | | app.on('window-all-closed') | Quit, except on macOS (process.platform !== 'darwin') | | app.on('activate') | macOS: re-open a window when dock icon clicked with none open | | contextBridge.exposeInMainWorld() | Expose preload APIs to the renderer safely | | electron . / npm start | Run the app from the project root |

Example

Complete minimal app — four files that actually run (npm i -D electron, then npm start).

// package.json — "main" tells Electron which script is the main process
{
  "name": "my-electron-app",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": { "start": "electron ." },
  "devDependencies": { "electron": "^42.0.0" }
}

// main.js — the MAIN process: Node.js, owns the app lifecycle
const { app, BrowserWindow } = require('electron/main')
const path = require('node:path')

const createWindow = () => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    // preload runs before page JS, with Node access the renderer lacks
    webPreferences: { preload: path.join(__dirname, 'preload.js') }
  })
  win.loadFile('index.html')
}

// Windows must be created AFTER the app is ready, never before.
app.whenReady().then(() => {
  createWindow()
  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow() // macOS
  })
})

// macOS apps stay alive when all windows close; others quit.
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit()
})

// preload.js — bridges main↔renderer; contextIsolation keeps it safe
const { contextBridge } = require('electron')
contextBridge.exposeInMainWorld('versions', {
  node: () => process.versions.node,
  electron: () => process.versions.electron
})

  
    
    
    Hello Electron
  
  
    Hello from Electron 👋
    
    
      // `versions` comes from preload via contextBridge, not Node directly.
      document.getElementById('info').innerText =
        `Node ${window.versions.node()} · Electron ${window.versions.electron()}`
    
  

Common mistakes

• Creating a BrowserWindow before app.whenReady() → crash/empty window. Always create windows inside app.whenReady().then(...).
• Calling require in the renderer → require is not defined. The renderer has no Node by default (contextIsolation on); expose APIs through a preload + contextBridge instead.
• Quitting on macOS — without the process.platform !== 'darwin' guard the app dies on window close, breaking macOS convention; pair it with the activate handler.
• Wrong/missing main field → Electron can't find your entry script. It must point at main.js.
• Relative preload path — use path.join(__dirname, 'preload.js'), not 'preload.js'.

Reference

Full API tables: [reference.md](reference.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ohvignas
• Source: ohvignas/claude-electron-skills
• License: MIT

Install and usage instructions live in the source repository linked above.