Getting Started with Electron

This chapter sets up a development environment and builds a first desktop app from an empty folder. Along the way you will scaffold a project with Electron Forge, the official tooling, and learn how to debug the main process from your editor.

Prepare Node.js

Electron is distributed as an npm package and driven by Node.js tooling, so install a Node.js LTS release first. Note that the Node.js running inside your app is the one embedded in Electron; the Node.js on your machine is used to install packages and run build tools.

node -v
npm -v

If both commands print a version, you are ready. If you ever need to compile native modules, you may also need the C++ build tools for Visual Studio on Windows or the Xcode Command Line Tools on macOS.

Build one by hand

Building a project manually once is the best way to see how the pieces fit together. Create a folder, generate a package.json, and install electron.

mkdir my-electron-app
cd my-electron-app
npm init -y
npm install --save-dev electron

Install electron as a dev dependency. Packaging tools bundle the Electron binary into your finished app themselves, so it does not belong among the runtime dependencies.

Next, point the main field of package.json at your entry file and add a start script. Running electron . reads the package.json in the current folder and launches the file named in main as the main process.

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "start": "electron ."
  }
}

Now write the main process in main.js. Once the app is ready (app.whenReady()), it creates a window and loads an HTML file.

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

function createWindow() {
  const win = new BrowserWindow({ width: 800, height: 600 })
  win.loadFile('index.html')
}

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

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

// Quit when all windows are closed, except on macOS
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit()
})

The index.html shown in the window is an ordinary web page. Adding a Content Security Policy from day one keeps unexpected scripts from running.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'" />
    <title>Hello Electron</title>
  </head>
  <body>
    <h1>Hello from Electron</h1>
  </body>
</html>