Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Electron Project Structure, Scripts and Tooling

Organize an Electron project into main, preload and renderer folders, choose between plain setup, Electron Forge and Vite templates, and wire dev scripts, DevTools and hot reload.

A three-file app is fine for learning, but real apps grow quickly. Before you add features, decide where each kind of code lives. A clear structure keeps the dangerous parts (code with Node.js power) separate from the web page code, and makes packaging, testing and security reviews much easier.

This lesson shows a recommended layout, the main tooling choices (plain npm, Electron Forge, Vite-based templates), and how to set up scripts, DevTools and automatic reload while you develop.

A layout that scales

Split the project by process, because that is how Electron itself divides responsibilities:

TEXT
my-app/
  package.json
  src/
    main/            # runs in the main process (Node.js)
      main.js
      windows.js
      ipc-handlers.js
    preload/         # runs in the renderer before the page, with limited power
      preload.js
    renderer/        # a normal web app: HTML, CSS, JS
      index.html
      app.js
      styles.css
  assets/            # icons, images
  build/             # packaging resources (icons per platform)
  out/               # packaged output (do not commit)

The rule that matters: code in renderer/ must never require('electron') or Node.js modules. It talks to the main process only through whatever the preload script chooses to expose. If you keep that rule visible in your folder names, a reviewer can instantly tell which code is privileged.

Add a .gitignore with at least node_modules/, out/ and dist/.

Choosing your tooling

There is no single required way to build an Electron app. These are the common starting points:

Option What you get Good for
Plain npm + electron Just the runtime and your own files Learning, tiny tools
Electron Forge Scaffolding, dev server, packagers and makers (installers) in one CLI Most new apps
Vite-based templates Fast hot reload for the renderer, TypeScript, React or Vue Apps with a modern front-end build
electron-builder Packaging and auto-update helpers, configured from package.json Teams who prefer its config style

Electron Forge is the official project's recommended toolchain. Creating an app looks like this (read-only; it needs Node.js and network access):

Terminal
npm init electron-app@latest my-app
cd my-app
npm start

Variants exist for a Vite template (-- --template=vite) and for TypeScript (-- --template=vite-typescript). Forge generates a forge.config.js, a src folder and scripts for start, package and make. The packaging details come in a later chapter; here you only need to know that Forge is a layer on top of the same concepts you are learning.

Scripts you will actually use

JSON
{
  "scripts": {
    "start": "electron .",
    "dev": "electronmon .",
    "lint": "eslint src",
    "test": "node --test"
  }
}

electronmon (a separate dev dependency) restarts the app when main-process files change and reloads renderer windows when their files change. For renderer-only changes you can also reload manually with Ctrl+R or Cmd+R inside the window, or call win.reload().

Know whether you are in development

Production and development behave differently: in development you want DevTools and verbose logs, in production you do not. Electron gives you app.isPackaged, which is false while you run electron . and true once the app is packaged.

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

function createWindow() {
  const win = new BrowserWindow({ width: 1000, height: 700 })
  win.loadFile('src/renderer/index.html')

  if (!app.isPackaged) {
    win.webContents.openDevTools({ mode: 'detach' })
  }
}

DevTools in Electron is the same Chrome DevTools you know: Elements, Console, Network, Sources and Performance. It inspects the renderer. For debugging the main process, start Electron with --inspect=5858 and attach Chrome's chrome://inspect or your editor's debugger.

Environment-specific paths

Where your files live changes after packaging. Source files sit in src/ during development, but inside an archive afterwards. Build paths relative to __dirname (the folder of the current file) rather than the current working directory, and use app.getPath() for places that belong to the user (documents, application data). Here is a stand-in that models the decisions so you can run them. It prints the paths a loader would choose, without touching the disk.

Node.js Stand-in: picking resource paths

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 preload path is derived from __dirname, so it works in both situations without an if.

CommonJS or ES modules?

Electron's main process supports both CommonJS (require) and ES modules (import, using .mjs or "type": "module"). The preload script has extra rules: with context isolation and sandboxing on (the secure defaults), a preload script is loaded in a restricted way, and it is simplest to write it as CommonJS. Many teams use TypeScript or a bundler so the question disappears; the bundler outputs files in the format each process needs.

Visualizing your project

A quick way to check that your layout keeps privileges separated is to list the files per process. This stand-in classifies paths by folder and flags any renderer file that imports Node.js or Electron directly:

Node.js Stand-in: flag risky renderer imports

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.

You can run the same idea as an ESLint rule in a real project (for example, restrict imports in src/renderer/**).

Quality tooling

Treat an Electron project like any JavaScript project: ESLint for code quality, Prettier for formatting, TypeScript if you want types for the Electron API (the electron package ships its own type definitions), and a test runner. A later chapter covers testing the app end to end.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why split source code into main, preload and renderer folders?

    The folders mirror the processes, so reviewers can see which code is privileged. It is a convention, not a requirement.
  2. 2. What does app.isPackaged tell you?

    It is false when you run electron . during development and true in a packaged application.
  3. 3. Why build file paths from __dirname instead of relative strings?

    __dirname is the folder of the current file, so the path stays correct wherever the app is launched from.
  4. 4. Which tool is the official recommended scaffolding and packaging toolchain?

    Electron Forge is recommended by the Electron project and combines scaffolding, dev server and installers.

Summary

  • Organize by process: main, preload, renderer.
  • Renderer code should not import Node.js or Electron modules directly.
  • Forge, Vite templates and electron-builder are the common tool choices; plain npm is fine to learn.
  • Use app.isPackaged and __dirname to behave correctly in development and production.
  • Open DevTools for the renderer in development; debug the main process with --inspect.

Next: The App Lifecycle and Its Events