Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Setting Up Your First Electron App

Install Node.js, create a project, add Electron, write main.js, index.html and package.json, and run your first desktop window with npm start. Includes runnable checks and a UI preview.

The smallest useful Electron app has three files: a package.json that names the entry point, a main.js that runs in Node.js and opens a window, and an index.html that the window displays. In this lesson you create all three, run them, and learn what each line does.

Electron itself cannot run inside this website, so the commands and the main-process code are shown read-only. Everything that can run safely here does: the page you build is plain HTML, so you can preview it live, and a small JavaScript checker verifies a package.json the same way Electron reads it.

Prerequisites

You need a recent LTS version of Node.js (which includes npm). Check it in a terminal:

Terminal
node --version
npm --version

Any editor works. You do not need to install Chromium: the electron npm package downloads a matching Electron binary for you the first time you install it.

Step 1: create the project

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

--save-dev records Electron under devDependencies. This is the convention, because packaging tools later bundle the Electron runtime themselves, so your app does not need it as a production dependency. Edit package.json so it looks like this:

JSON
{
  "name": "my-first-app",
  "version": "1.0.0",
  "description": "My first Electron app",
  "main": "main.js",
  "scripts": {
    "start": "electron ."
  },
  "devDependencies": {
    "electron": "^40.0.0"
  }
}

Two fields matter most. "main" tells Electron which file is the main process entry point. "scripts.start" lets you launch the app with npm start; the . means "run the app in the current folder", and Electron reads main from its package.json. Your version number for electron will differ; use whatever npm install wrote.

Step 2: write the main process

Create main.js:

JavaScript
const { app, BrowserWindow } = require('electron')
const path = require('node:path')

function createWindow() {
  const win = new BrowserWindow({
    width: 900,
    height: 600,
    title: 'My First App',
  })

  win.loadFile(path.join(__dirname, 'index.html'))
}

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

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

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

Walk through it:

  1. require('electron') returns the Electron API. app controls the application lifecycle and BrowserWindow creates windows.
  2. new BrowserWindow({...}) creates a native window with Chromium inside. Options such as width and height are in device-independent pixels.
  3. win.loadFile(...) loads a local HTML file into the window, like typing a file path into a browser.
  4. app.whenReady() returns a promise that resolves after Electron finishes initializing. Create windows only inside it.
  5. The activate handler is macOS behavior: clicking the dock icon of an app with no windows should open one again.
  6. The window-all-closed handler quits on Windows and Linux when the last window closes, but keeps the app alive on macOS, where apps conventionally stay running without windows.

The lifecycle lesson goes deeper into these events.

Step 3: write the page

Create index.html. This is just a web page:

HTML
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'" />
    <title>My First App</title>
  </head>
  <body>
    <h1>Hello from Electron</h1>
    <p>Chromium is rendering this page.</p>
  </body>
</html>

The Content-Security-Policy meta tag tells Chromium to load only resources from the app itself. It is a good habit from day one, and the security chapter explains why. Run the app:

Terminal
npm start

A window titled "My First App" opens with your heading. Close it and, on Windows or Linux, the process ends.

Preview the page you just built

Because the renderer is ordinary web content, you can design it right here. This preview uses the same HTML and a little CSS; try changing the greeting and the colors.

The renderer is just a web page

In real Electron the script would also be able to use Chromium features such as fetch and the DOM, but not Node.js APIs, unless you opt in (which you should not). That separation is the subject of the next chapter.

Check your package.json like Electron does

When you run electron ., Electron looks for package.json, reads main, and fails with a clear error if the file is missing. This stand-in reproduces that decision logic on an in-memory project so you can see which mistakes break a launch.

Node.js Stand-in: resolving the entry point

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The most common beginner failure is exactly the typo case: the main field pointing at a file that does not exist.

Common problems

  • A blank white window: loadFile was given a wrong path. Use path.join(__dirname, 'index.html') so it does not depend on the current directory.
  • "Cannot find module 'electron'": you ran node main.js instead of npm start. The electron module only exists inside the Electron runtime.
  • The window opens before ready: you created it at the top level. Move it into app.whenReady().then(...).
  • The download of Electron fails: a proxy or firewall blocked the install; retry on a different network or set the proxy variables for npm.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which package.json field tells Electron where the main process starts?

    The main field names the file that runs in the main process; the start script only launches Electron.
  2. 2. Why is electron usually installed with --save-dev?

    When you package the app the Electron runtime is bundled by the packager, so it does not need to be a production dependency.
  3. 3. What does win.loadFile('index.html') do?

    loadFile points the window's Chromium at a local file, like opening it in a browser tab.
  4. 4. On Windows and Linux, when does the sample app quit?

    The window-all-closed handler calls app.quit() unless the platform is macOS (darwin).

Summary

  • A minimal app is package.json (with main), main.js and index.html.
  • Install Electron as a dev dependency and launch with npm start (electron .).
  • Create windows inside app.whenReady(); handle activate and window-all-closed for platform conventions.
  • Use path.join(__dirname, ...) for file paths.
  • Add a Content Security Policy to your page from the start.

Next: Project Structure, Scripts and Tooling