TL;DR: A step-by-step tutorial explaining how to create a desktop application using Create React App (CRA) and Electron. You can find the source code of the project on GitHub.

Originally published at mmazzarolo.com

I recently needed to wrap a React app generated with Create React App (CRA) with Electron (well, the app itself uses React Native for Web, but it doesn’t matter).

My goal was to stay within the Create React App limits as much as possible (without ejecting).

There’s no shortage of guides on how to do it online. Still, I couldn’t find one that fully follows the Electron security guidelines and provides a distribution setup using Electron-builder.

So, here’s yet another tutorial on how to wrap an app built with Create React App in Electron — from the initial scaffolding up to the distribution workflow.

React app scaffolding

Let’s start from an “empty” React app generated with Create React App.

# Using npx (https://www.npmjs.com/package/npx) to run create-react-app.
npx create-react-app my-electron-app

Then, add the following dependencies (most of them are here only to simplify the development flow):

cd my-electron-app
yarn add -D concurrently cross-env electron electron-builder electronmon wait-on

• concurrently: Run multiple commands concurrently. We’ll use it to run both the Electron process and the react app in watch mode.
• cross-env: Run scripts that set and use environment variables across different platforms. We’ll use it to make our scripts compatible with both Unix and Windows OSes.
• electron: The core framework for creating the app.
• electron-builder: A complete solution to package and build a ready for distribution Electron app for macOS, Windows, and Linux.
• electronmon: Like nodemon, but for the Electron process. Allows watching and reloading our Electron app.
• wait-on: Utility to wait for files, ports, sockets, etc. We’ll use it to wait for the react app to be built before we open the Electron app (while developing).

Electron’s main script

The next step is creating Electron’s main script. This script controls the main process, which runs in a full Node.js environment and is responsible for managing your app’s lifecycle, displaying native interfaces, performing privileged operations, and managing renderer processes.

Electron’s main script is often named main.js and stored in <project-root>/electron/main.js, but in our case, we’ll name it electron.js (to disambiguate it) and store it in <project-root>/public/electron.js (so that Create React App will automatically copy it in the build directory).

// public/electron.js

// Module to control the application lifecycle and the native browser window.
const { app, BrowserWindow, protocol } = require("electron");
const path = require("path");
const url = require("url");

// Create the native browser window.
function createWindow() {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    // Set the path of an additional "preload" script that can be used to
    // communicate between node-land and browser-land.
    webPreferences: {
      preload: path.join(__dirname, "preload.js"),
    },
  });

  // In production, set the initial browser path to the local bundle generated
  // by the Create React App build process.
  // In development, set it to localhost to allow live/hot-reloading.
  const appURL = app.isPackaged
    ? url.format({
        pathname: path.join(__dirname, "index.html"),
        protocol: "file:",
        slashes: true,
      })
    : "http://localhost:3000";
  mainWindow.loadURL(appURL);

  // Automatically open Chrome's DevTools in development mode.
  if (!app.isPackaged) {
    mainWindow.webContents.openDevTools();
  }
}

// Setup a local proxy to adjust the paths of requested files when loading
// them from the local production bundle (e.g.: local fonts, etc...).
function setupLocalFilesNormalizerProxy() {
  protocol.registerHttpProtocol(
    "file",
    (request, callback) => {
      const url = request.url.substr(8);
      callback({ path: path.normalize(`${__dirname}/${url}`) });
    },
    (error) => {
      if (error) console.error("Failed to register protocol");
    }
  );
}

// This method will be called when Electron has finished its initialization and
// is ready to create the browser windows.
// Some APIs can only be used after this event occurs.
app.whenReady().then(() => {
  createWindow();
  setupLocalFilesNormalizerProxy();

  app.on("activate", function () {
    // On macOS it's common to re-create a window in the app when the
    // dock icon is clicked and there are no other windows open.
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow();
    }
  });
});

// Quit when all windows are closed, except on macOS.
// There, it's common for applications and their menu bar to stay active until
// the user quits explicitly with Cmd + Q.
app.on("window-all-closed", function () {
  if (process.platform !== "darwin") {
    app.quit();
  }
});

// If your app has no need to navigate or only needs to navigate to known pages,
// it is a good idea to limit navigation outright to that known scope,
// disallowing any other kinds of navigation.
const allowedNavigationDestinations = "https://my-electron-app.com";
app.on("web-contents-created", (event, contents) => {
  contents.on("will-navigate", (event, navigationUrl) => {
    const parsedUrl = new URL(navigationUrl);

    if (!allowedNavigationDestinations.includes(parsedUrl.origin)) {
      event.preventDefault();
    }
  });
});

// In this file you can include the rest of your app's specific main process
// code. You can also put them in separate files and require them here.

Yeah, this is not a "minimal" electron.js setup, but I wanted some nice defaults and made sure we're following Electron's security guidelines.

During execution, Electron will look for this script in the main field of the app’s package.json config, so let’s update it:

{
  "name": "my-electron-app",
  "version": "0.1.0",
  "private": true,
+ "main": "./public/electron.js",
  "dependencies": {

Electron’s preload script

By default, the process running in your browser won’t be able to communicate with the Node.js process. Electron solves this problem by allowing the use of a preload script: a script that runs before the renderer process is loaded and has access to both renderer globals (e.g., window and document) and a Node.js environment.

In our electron.js script, we already specified that we expect a preload script to be loaded from <project-root>/public/preload.js. So, let’s create it:

// public/preload.js

// All of the Node.js APIs are available in the preload process.
// It has the same sandbox as a Chrome extension.
const { contextBridge } = require("electron");

// As an example, here we use the exposeInMainWorld API to expose the browsers
// and node versions to the main window.
// They'll be accessible at "window.versions".
process.once("loaded", () => {
  contextBridge.exposeInMainWorld("versions", process.versions);
});

The above code accesses the Node.js process.versions object and exposes it in the react app, making it accessible at window.versions.

Making Create React App compatible with Electron

Our goal is to stay within the Create React App ecosystem without ejecting and use Electron only to render the React app.

To do so, a few tweaks are needed.

Update the homepage property

We need to enforce Create React App to infer a relative root path in the generated HTML file. This is a requirement because we’re not going to serve the HTML file; it will be loaded directly by Electron. To do so, we can set the homepage property of the package.json to ./ (see Building For Relative Paths in the Create React App documentation for more details).

{
  "name": "my-electron-app",
  "version": "0.1.0",
  "private": true,
+ "homepage": "./",
  "main": "./public/electron.js",
  "dependencies": {

Update browserslist’s targets

Update the browserslist section of package.json to support only the latest Electron version. This ensures Webpack/Babel will only add the polyfills and features we strictly need, keeping the bundle size to the minimum.

  "browserslist": {
    "production": [
+     "last 1 electron version",
-      ">0.2%",
-     "not dead",
-     "not op_mini all"
    ],
    "development": [
+     "last 1 electron version",
-     "last 1 chrome version",
-     "last 1 firefox version",
-     "last 1 safari version"
    ]
  },

Define a Content Security Policy

A Content Security Policy (CSP) is an additional layer of protection against cross-site scripting attacks and data injection attacks. So I highly recommend to enable it in <project-root>/public/index.html.

The following CSP will allow Electron to run only inline scripts (the ones injected in the HTML file by Create React App’s build process).

    <meta name="theme-color" content="#000000" />
    <meta
      name="description"
      content="Web site created using create-react-app"
    />
+   <meta
+     http-equiv="Content-Security-Policy"
+     content="script-src 'self' 'unsafe-inline';"
+   />

Please keep in mind this is just a minimal CSP example. You can tweak it further to allow-list only specific websites, and you can make it even stricter by generating a nonce to load only the inline scripts you generated in the build process. See Content Security Policy (CSP) on MDN Web Docs for more info.

Define the start/development script

In your package.json, define a script to build the Create React App and start the Electron process in watch mode:

  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
+   "electron:start": "concurrently -k \"cross-env BROWSER=none yarn start\" \"wait-on http://localhost:3000 && electronmon .\""
  },

Here’s a breakdown of what it does:

• concurrently -k invokes the subsequent commands in parallel, and kill both of them when the process is stopped.
• cross-env BROWSER=none yarn start sets the BROWSER=none environment variables (using cross-env for Windows compatibility) to disable the automatic opening of the browser and invokes the start script, which runs the Create React App build in watch-mode.
• wait-on http://localhost:3000 && electronmon . waits for the Create React App dev-server to serve the app on localhost:3000, and then invokes electronmon . to start the Electron add in watch-mode.

You can now run yarn electron:start to run your React app within Electron instead of the browser window.

Package the the Electron app for distribution

Finally, we need to make a few minor changes to the Create React App setup to generate platform-specific distributables so that our app can be installed. We’ll use Electron-builder, a configuration-based solution to package and build ready for distribution Electron apps for macOS, Windows, and Linux.

Electron-builder offers a ton of configuration options, but for the sake of simplicity in this guide we’ll add just the bare minimum settings to create working distributable files.

Set the app author and description

Electron-builder infers a few default info required to bundle the distributable file (app name, author, and description) from the package.json, so let’s specify them:

  "name": "my-electron-app",
  "version": "0.1.0",
  "private": true,
+ "author": "John Doe",
+ "description": "My fantastic Electron app",
  "homepage": "./",
  "main": "./public/electron.js",
  "dependencies": {

Set the build configuration

Let’s add a minimal Electron-builder configuration in the package.json using the build key on top level:

+ "build": {
+   "appId": "com.electron.myapp",
+   "productName": "My Electron App",
+   "files": ["build/ **/*", "node_modules/** /*"],
+   "directories": {
+     "buildResources": "public"
+   },
+   "mac": {
+     "target": "dmg"
+   },
+   "win": {
+     "target": "nsis"
+   },
+   "linux": {
+     "target": "deb"
+   }
+ }

• appId: The application ID used to identify the app in the macOS (as CFBundleIdentifier) and Windows (as App User Model ID).
• productName: The name of the app, as shown in the app executable.
• directories.buildResources: Path of the root dir that holds resources not packed into the app.
• files: Global of additional files (outside of directories.buildResources) required by the app to run.
• mac, win, linux: Platform-specific configurations.

Add an app icon

By default, Electron-builder will look for an app icon in <root-project>/build/icon.png — so you should be good to go as long as you put it in the public directory (Create React App build process will take care of moving it to the build directory).

For more info, see the Electron-builder icons documentation.

Add the packaging scripts

Finally, to make Electron-builder package our app we can add a packaging script for each destination platform in the package.json:

  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
    "electron:start": "concurrently -k \"cross-env BROWSER=none yarn start\" \"wait-on http://localhost:3000 && electronmon .\"",
+   "electron:package:mac": "yarn build && electron-builder -m -c.extraMetadata.main=build/electron.js",
+   "electron:package:win": "yarn build && electron-builder -w -c.extraMetadata.main=build/electron.js",
+   "electron:package:linux": "yarn build && electron-builder -l -c.extraMetadata.main=build/electron.js"
  },

These commands will build a React app production bundle and package it into distributables for Windows, macOS, and Linux respectively. By default, the distributables will be in NSIS (Windows), dmg (macOS), and deb (Linux) form.

The generated distributable files will be place in <project-root>/dist, so make sure to add this directory to .gitignore:

+ /dist

Summary

That’s it.

You can now run yarn electron:start to kickstart your development flow, and yarn electron:package:<platform> to generate a distributable bundle.

Please keep in mind that the project created with this tutorial represents what I consider the bare minimum to requirements to wrap a React app with Electron. I highly recommend taking some time to read the Electron and Electron-builder official documentation to tweak your setup.

You can find the complete code for this blog post on GitHub.