Quick Start

This guide will step you through the process of creating a barebones Hello World app in Electron, similar to electron/electron-quick-start.

By the end of this tutorial, your app will open a browser window that displays a web page with information about which Chromium, Node.js, and Electron versions are running.

Prerequisites

To use Electron, you need to install Node.js. We recommend that you use the latest LTS version available.

Please install Node.js using pre-built installers for your platform. You may encounter incompatibility issues with different development tools otherwise.

To check that Node.js was installed correctly, type the following commands in your terminal client:

  1. node -v
  2. npm -v

The commands should print the versions of Node.js and npm accordingly.

Note: Since Electron embeds Node.js into its binary, the version of Node.js running your code is unrelated to the version running on your system.

Create your application

Scaffold the project

Electron apps follow the same general structure as other Node.js projects. Start by creating a folder and initializing an npm package.

```sh npm2yarn mkdir my-electron-app && cd my-electron-app npm init

  2. The interactive `init` command will prompt you to set some fields in your config.
  3. There are a few rules to follow for the purposes of this tutorial:
  5. * `entry point` should be `main.js`.
  6. * `author` and `description` can be any value, but are necessary for
  7. [app packaging](#package-and-distribute-your-application).
  9. Your `package.json` file should look something like this:
  11. ```json
  12. {
  13.   "name": "my-electron-app",
  14.   "version": "1.0.0",
  15.   "description": "Hello World!",
  16.   "main": "main.js",
  17.   "author": "Jane Doe",
  18.   "license": "MIT"
  19. }

Then, install the electron package into your app’s devDependencies.

```sh npm2yarn $ npm install —save-dev electron

  2. > Note: If you're encountering any issues with installing Electron, please
  3. > refer to the [Advanced Installation][advanced-installation] guide.
  5. Finally, you want to be able to execute Electron. In the [`scripts`][package-scripts]
  6. field of your `package.json` config, add a `start` command like so:
  8. ```json
  9. {
  10.   "scripts": {
  11.     "start": "electron ."
  12.   }
  13. }

This start command will let you open your app in development mode.

```sh npm2yarn npm start

  2. > Note: This script tells Electron to run on your project's root folder. At this stage,
  3. > your app will immediately throw an error telling you that it cannot find an app to run.
  5. [advanced-installation]: ./installation.md
  6. [package-scripts]: https://docs.npmjs.com/cli/v7/using-npm/scripts
  8. ### Run the main process
  10. The entry point of any Electron application is its `main` script. This script controls the
  11. **main process**, which runs in a full Node.js environment and is responsible for
  12. controlling your app's lifecycle, displaying native interfaces, performing privileged
  13. operations, and managing renderer processes (more on that later).
  15. During execution, Electron will look for this script in the [`main`][package-json-main]
  16. field of the app's `package.json` config, which you should have configured during the
  17. [app scaffolding](#scaffold-the-project) step.
  19. To initialize the `main` script, create an empty file named `main.js` in the root folder
  20. of your project.
  22. > Note: If you run the `start` script again at this point, your app will no longer throw
  23. > any errors! However, it won't do anything yet because we haven't added any code into
  24. > `main.js`.
  26. [package-json-main]: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#main
  28. ### Create a web page
  30. Before we can create a window for our application, we need to create the content that
  31. will be loaded into it. In Electron, each window displays web contents that can be loaded
  32. from either a local HTML file or a remote URL.
  34. For this tutorial, you will be doing the former. Create an `index.html` file in the root
  35. folder of your project:
  37. ```html
  38. <!DOCTYPE html>
  39. <html>
  40.   <head>
  41.     <meta charset="UTF-8">
  42.     <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
  43.     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
  44.     <meta http-equiv="X-Content-Security-Policy" content="default-src 'self'; script-src 'self'">
  45.     <title>Hello World!</title>
  46.   </head>
  47.   <body>
  48.     <h1>Hello World!</h1>
  49.     We are using Node.js <span id="node-version"></span>,
  50.     Chromium <span id="chrome-version"></span>,
  51.     and Electron <span id="electron-version"></span>.
  52.   </body>
  53. </html>

Note: Looking at this HTML document, you can observe that the version numbers are missing from the body text. We’ll manually insert them later using JavaScript.

Opening your web page in a browser window

Now that you have a web page, load it into an application window. To do so, you’ll need two Electron modules:

  • The app module, which controls your application’s event lifecycle.
  • The BrowserWindow module, which creates and manages application windows.

Because the main process runs Node.js, you can import these as CommonJS modules at the top of your file:

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

Then, add a createWindow() function that loads index.html into a new BrowserWindow instance.

  1. const createWindow = () => {
  2.   const win = new BrowserWindow({
  3.     width: 800,
  4.     height: 600
  5.   })
  7.   win.loadFile('index.html')
  8. }

Next, call this createWindow() function to open your window.

In Electron, browser windows can only be created after the app module’s ready event is fired. You can wait for this event by using the app.whenReady() API. Call createWindow() after whenReady() resolves its Promise.

  1. app.whenReady().then(() => {
  2.   createWindow()
  3. })

Note: At this point, your Electron application should successfully open a window that displays your web page!

Manage your window’s lifecycle

Although you can now open a browser window, you’ll need some additional boilerplate code to make it feel more native to each platform. Application windows behave differently on each OS, and Electron puts the responsibility on developers to implement these conventions in their app.

In general, you can use the process global’s platform attribute to run code specifically for certain operating systems.

Quit the app when all windows are closed (Windows & Linux)

On Windows and Linux, exiting all windows generally quits an application entirely.

To implement this, listen for the app module’s 'window-all-closed' event, and call app.quit() if the user is not on macOS (darwin).

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

Open a window if none are open (macOS)

Whereas Linux and Windows apps quit when they have no windows open, macOS apps generally continue running even without any windows open, and activating the app when no windows are available should open a new one.

To implement this feature, listen for the app module’s activate event, and call your existing createWindow() method if no browser windows are open.

Because windows cannot be created before the ready event, you should only listen for activate events after your app is initialized. Do this by attaching your event listener from within your existing whenReady() callback.

  1. app.whenReady().then(() => {
  2.   createWindow()
  4.   app.on('activate', () => {
  5.     if (BrowserWindow.getAllWindows().length === 0) createWindow()
  6.   })
  7. })

Note: At this point, your window controls should be fully functional!

Access Node.js from the renderer with a preload script

Now, the last thing to do is print out the version numbers for Electron and its dependencies onto your web page.

Accessing this information is trivial to do in the main process through Node’s global process object. However, you can’t just edit the DOM from the main process because it has no access to the renderer’s document context. They’re in entirely different processes!

Note: If you need a more in-depth look at Electron processes, see the Process Model document.

This is where attaching a preload script to your renderer comes in handy. A preload script runs before the renderer process is loaded, and has access to both renderer globals (e.g. window and document) and a Node.js environment.

Create a new script named preload.js as such:

  1. window.addEventListener('DOMContentLoaded', () => {
  2.   const replaceText = (selector, text) => {
  3.     const element = document.getElementById(selector)
  4.     if (element) element.innerText = text
  5.   }
  7.   for (const dependency of ['chrome', 'node', 'electron']) {
  8.     replaceText(`${dependency}-version`, process.versions[dependency])
  9.   }
  10. })

The above code accesses the Node.js process.versions object and runs a basic replaceText helper function to insert the version numbers into the HTML document.

To attach this script to your renderer process, pass in the path to your preload script to the webPreferences.preload option in your existing BrowserWindow constructor.

  1. // include the Node.js 'path' module at the top of your file
  2. const path = require('path')
  4. // modify your existing createWindow() function
  5. const createWindow = () => {
  6.   const win = new BrowserWindow({
  7.     width: 800,
  8.     height: 600,
  9.     webPreferences: {
  10.       preload: path.join(__dirname, 'preload.js')
  11.     }
  12.   })
  14.   win.loadFile('index.html')
  15. }
  16. // ...

There are two Node.js concepts that are used here:

  • The __dirname string points to the path of the currently executing script (in this case, your project’s root folder).
  • The path.join API joins multiple path segments together, creating a combined path string that works across all platforms.

We use a path relative to the currently executing JavaScript file so that your relative path will work in both development and packaged mode.

Bonus: Add functionality to your web contents

At this point, you might be wondering how to add more functionality to your application.

For any interactions with your web contents, you want to add scripts to your renderer process. Because the renderer runs in a normal web environment, you can add a <script> tag right before your index.html file’s closing </body> tag to include any arbitrary scripts you want:

  1. <script src="./renderer.js"></script>

The code contained in renderer.js can then use the same JavaScript APIs and tooling you use for typical front-end development, such as using webpack to bundle and minify your code or React to manage your user interfaces.

Recap

After following the above steps, you should have a fully functional Electron application that looks like this:

Simplest Electron app

The full code is available below:

  1. // main.js
  3. // Modules to control application life and create native browser window
  4. const { app, BrowserWindow } = require('electron')
  5. const path = require('path')
  7. const createWindow = () => {
  8.   // Create the browser window.
  9.   const mainWindow = new BrowserWindow({
  10.     width: 800,
  11.     height: 600,
  12.     webPreferences: {
  13.       preload: path.join(__dirname, 'preload.js')
  14.     }
  15.   })
  17.   // and load the index.html of the app.
  18.   mainWindow.loadFile('index.html')
  20.   // Open the DevTools.
  21.   // mainWindow.webContents.openDevTools()
  22. }
  24. // This method will be called when Electron has finished
  25. // initialization and is ready to create browser windows.
  26. // Some APIs can only be used after this event occurs.
  27. app.whenReady().then(() => {
  28.   createWindow()
  30.   app.on('activate', () => {
  31.     // On macOS it's common to re-create a window in the app when the
  32.     // dock icon is clicked and there are no other windows open.
  33.     if (BrowserWindow.getAllWindows().length === 0) createWindow()
  34.   })
  35. })
  37. // Quit when all windows are closed, except on macOS. There, it's common
  38. // for applications and their menu bar to stay active until the user quits
  39. // explicitly with Cmd + Q.
  40. app.on('window-all-closed', () => {
  41.   if (process.platform !== 'darwin') app.quit()
  42. })
  44. // In this file you can include the rest of your app's specific main process
  45. // code. You can also put them in separate files and require them here.
  1. // preload.js
  3. // All of the Node.js APIs are available in the preload process.
  4. // It has the same sandbox as a Chrome extension.
  5. window.addEventListener('DOMContentLoaded', () => {
  6.   const replaceText = (selector, text) => {
  7.     const element = document.getElementById(selector)
  8.     if (element) element.innerText = text
  9.   }
  11.   for (const dependency of ['chrome', 'node', 'electron']) {
  12.     replaceText(`${dependency}-version`, process.versions[dependency])
  13.   }
  14. })
  1. <!--index.html-->
  3. <!DOCTYPE html>
  4. <html>
  5.   <head>
  6.     <meta charset="UTF-8">
  7.     <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
  8.     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
  9.     <meta http-equiv="X-Content-Security-Policy" content="default-src 'self'; script-src 'self'">
  10.     <title>Hello World!</title>
  11.   </head>
  12.   <body>
  13.     <h1>Hello World!</h1>
  14.     We are using Node.js <span id="node-version"></span>,
  15.     Chromium <span id="chrome-version"></span>,
  16.     and Electron <span id="electron-version"></span>.
  18.     <!-- You can also require other files to run in this process -->
  19.     <script src="./renderer.js"></script>
  20.   </body>
  21. </html>

```fiddle docs/fiddles/quick-start

  2. To summarize all the steps we've done:
  4. * We bootstrapped a Node.js application and added Electron as a dependency.
  5. * We created a `main.js` script that runs our main process, which controls our app
  6.   and runs in a Node.js environment. In this script, we used Electron's `app` and
  7.   `BrowserWindow` modules to create a browser window that displays web content
  8.   in a separate process (the renderer).
  9. * In order to access certain Node.js functionality in the renderer, we attached
  10.   a preload script to our `BrowserWindow` constructor.
  12. ## Package and distribute your application
  14. The fastest way to distribute your newly created app is using
  15. [Electron Forge](https://www.electronforge.io).
  17. 1. Add Electron Forge as a development dependency of your app, and use its `import` command to set up
  18. Forge's scaffolding:
  20.    ```sh npm2yarn
  21.    npm install --save-dev @electron-forge/cli
  22.    npx electron-forge import
  24.    ✔ Checking your system
  25.    ✔ Initializing Git Repository
  26.    ✔ Writing modified package.json file
  27.    ✔ Installing dependencies
  28.    ✔ Writing modified package.json file
  29.    ✔ Fixing .gitignore
  31.    We have ATTEMPTED to convert your app to be in a format that electron-forge understands.
  33.    Thanks for using "electron-forge"!!!

  1. Create a distributable using Forge’s make command:

    ```sh npm2yarn npm run make

    my-electron-app@1.0.0 make /my-electron-app electron-forge make

    ✔ Checking your system ✔ Resolving Forge Config We need to package your application before we can make it ✔ Preparing to Package Application for arch: x64 ✔ Preparing native dependencies ✔ Packaging Application Making for the following targets: zip ✔ Making for target: zip - On platform: darwin - For arch: x64

    2. Electron Forge creates the `out` folder where your package will be located:
    4. ```plain
    5. // Example for macOS
    6. out/
    7. ├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip
    8. ├── ...
    9. └── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app