Cordova Electron

Electron is a framework that uses web technologies (HTML, CSS, and JS) to build cross-platform desktop applications.

• Cordova Electron
  • System Requirements
    • Linux
    • Mac
    • Windows
  • Quick Start
    • Create a Project
    • Preview a Project
    • Build a Project
  • Customizing the Application's Icon
  • Customizing the Application's Main Process
    • Window Appearance (BrowserWindow)
      • How to set the window default size?
      • How to make the window not resizable?
      • How to make my window fullscreen?
    • DevTools
  • Build Configurations
    • Default Build Configurations
    • Customizing Build Configurations
      • Adding a package
      • Setting the package arch
    • Multi-Platform Build Support
  • Signing Configurations
    • macOS Signing
    • Windows Signing
    • Linux Signing
  • Plugins

System Requirements

Linux

@todo Add Linux Requirements here.

Mac

• Xcode, the IDE for macOS, comes bundled with necessary software development tools to code signing and compiling native code for macOS.

• RedHat Build Support

  • Homebrew, one of the available macOS package manager, is used for installing additional tools and dependencies. Homebrew will be needed to install RPM packaging dependencies. Brew Install Step

  • RPM, a standard package manager for multiple Linux distributions, is the tool used for creating the Linux RPM package. To install this tool, use the following Homebrew command:

    $ brew install rpm
    

Windows

@todo Review and Update Windows Requirements.

• PowerShell, for Windows 7 users, must be at version 3.0 or greater for app signing.

Quick Start

Create a Project

$ npm i -g cordova
$ cordova create sampleApp
$ cd sampleApp
$ cordova platform add electron

Notice: If using Cordova CLI prior to version 9.x, you will need to use the cordova-electron argument instead of electron for any command that requires the platform's name. For example:

$ cordova platform add cordova-electron
$ cordova run cordova-electron

Preview a Project

It is not necessary to build the Electron application for previewing. Since the building process can be slow, it is recommended to pass in the --no-build flag to disable the build process when previewing.

$ cordova run electron --no-build

Build a Project

Debug Builds

$ cordova build electron
$ cordova build electron --debug

Release Builds

$ cordova build electron --release

Customizing the Application's Icon

Customized icon(s) can be declared with the <icon> element(s) in the config.xml file. There are two types of icons that can be defined, the application icon and the package installer icon. These icons should be defined in the Electron's platform node <platform name="electron">.

One icon can be used for the application and installer, but this icon should be at least 512x512 pixels to work across all operating systems.

Notice: If a customized icon is not provided, the Apache Cordova default icons are used.

Notice: macOS does not display custom icons when using cordova run. It defaults to the Electron's icon.

<platform name="electron">
  <icon src="res/electron/icon.png" />
</platform>

You can supply unique icons for the application and installer by setting the target attribute. As mentioned above, the installer image should be 512x512 pixels to work across all platforms.

<platform name="electron">
  <icon src="res/electron/app.png" target="app" />
  <icon src="res/electron/installer.png" target="installer" />
</platform>

For devices that support high-DPI resolutions, such as Apple's Retina display, you can create a set of images with the same base filename but suffix with its multiplier.

For example, if the base image's filename icon.png and is the standard resolution, then icon@2x.png will be treated as a high-resolution image that with a DPI doubled from the base.

• icon.png (256px x 256px)
• icon@2x.png (512px x 512px)

If you want to support displays with different DPI densities at the same time, you can put images with different sizes in the same folder and use the filename without DPI suffixes. For example:

<platform name="electron">
  <icon src="res/electron/icon.png" />
  <icon src="res/electron/icon@1.5x.png" />
  <icon src="res/electron/icon@2x.png" />
  <icon src="res/electron/icon@4x.png" target="installer" />
</platform>

Customizing the Application's Main Process

In the {PROJECT_ROOT_DIR}/platform/electron/platform_www/ directory, the file main.js defines the application‘s main process. We can customize the application’s window appearance as well as defining or enabling additional features in this file.

Window Appearance (BrowserWindow)

Electron provides many options to manipulate the BrowserWindow. This section covers only a few basic options. For a full list of options, please see the Electron's Docs - BrowserWindow Options.

Electron provides many optional options that can manipulate the BrowserWindow. This section will cover a few of these options that many uses. A full list of these options can be found on the

How to set the window default size?

Using the width and height option, you can define starting default window size.

mainWindow = new BrowserWindow({
  width: 800,
  height: 600
});

How to make the window not resizable?

Using the resizable flag option, you can disable the user‘s ability to resize your application’s window.

mainWindow = new BrowserWindow({ resizable: false });

How to make my window fullscreen?

Using the fullscreen flag option, you can force the application to launch in fullscreen.

mainWindow = new BrowserWindow({ fullscreen: true });

DevTools

The --release and --debug flags control the visibility of the DevTools. DevTools are shown by default on Debug Builds (without a flag or with --debug). If you want to hide the DevTools pass in the --release flag when building or running the application.

Note: DevTools still can be closed or opened manually.

Build Configurations

Default Build Configurations

By default, with no additional configuration, cordova build electron will build default packages for the host operating system (OS) that triggers the command. Below, are the list of default packages for each OS.

Linux

Package	Arch
tar.gz	x64

Mac

Package	Arch
dmg	x64
zip	x64

Windows

Package	Arch
nsis	x64

Customizing Build Configurations

If for any reason you would like to customize the build configurations, modifications are placed within the build.json file located in the project's root directory. E.g. {PROJECT_ROOT_DIR}/build.json. This file contains all build configurations for all platforms (Android, Electron, iOS, Windows).

Example Config Structure

{
  "electron": {}
}

Since the Electron framework is for creating cross-platform applications, multiple configurations are required for each OS build. The electron node, in the build.json file, contains three properties that separate the build configurations for each OS.

Example Config Structure with Each Platform

{
  "electron": {
    linux: {},
    mac: {},
    windows: {}
  }
}

Each OS node contains properties that are used to identify what package to generate and how to sign.

OS Properties:

• package is an array of package formats that will be generated.
• arch is an array of architectures that each package is built for.
• signing is an object that contains signing information. See Signing Configurations for more information.

Any properties that are undefined will fallback to default values.

Adding a package

The package property is an array list of packages to be outputted. If the property is defined, the default packages are not used unless added. The order of the packages has no importance.

The configuration example below will generate tar.gz, dmg and zip packages for macOS.

{
  "electron": {
    "mac": {
      "package": [
        "dmg",
        "tar.gz",
        "zip"
      ]
    }
  }
}

Available Packages by Operating System

Package Type	Linux	macOS	Windows
default	-	dmg zip	-
dmg	-	:white_check_mark:	-
mas	-	:white_check_mark:	-
mas-dev	:white_check_mark:	-	-
pkg	-	:white_check_mark:	-
7z	:white_check_mark:	:white_check_mark:	:white_check_mark:
zip	:white_check_mark:	:white_check_mark:	:white_check_mark:
tar.xz	:white_check_mark:	:white_check_mark:	:white_check_mark:
tar.lz	:white_check_mark:	:white_check_mark:	:white_check_mark:
tar.gz	:white_check_mark:	:white_check_mark:	:white_check_mark:
tar.bz2	:white_check_mark:	:white_check_mark:	:white_check_mark:
dir	:white_check_mark:	:white_check_mark:	:white_check_mark:
nsis	-	-	:white_check_mark:
nsis-web	-	-	:white_check_mark:
portable	-	-	:white_check_mark:
appx	-	-	:white_check_mark: [1]
msi	-	-	:white_check_mark:
AppImage	:white_check_mark:	-	-
snap	:white_check_mark:	-	-
deb	:white_check_mark:	-	-
rpm	:white_check_mark:	-	-
freebsd	:white_check_mark:	-	-
pacman	:white_check_mark:	-	-
p5p	:white_check_mark:	-	-
apk	:white_check_mark:	-	-

• [1] Only Window 10 can build AppX packages.

Setting the package arch

The arch property is an array list of architectures that each package is built for. When the property is defined, the default arch is not used unless added.

:warning: Not all architectures are available for every operating system. Please review the Electron Releases to identify valid combinations. For example, macOS (Darwin) only supports x64.

Available Arch

• ia32
• x64
• armv71
• arm64

The example above will generate a x64 dmg package.

{
  "electron": {
    "mac": {
      "package": [
        "dmg"
      ],
      "arch": ["x64"]
    }
  }
}

Multi-Platform Build Support

:warning: Not all platforms support this feature and may have limitations.

Building for multiple platforms on a single operating system may possible but has limitations. It is recommended that the builder's operating system (host OS) matches with the platform that is being built.

The matrix below shows each host OS and for which platforms they are capable of building applications.

Host [1]	Linux	Mac	Window
Linux	:white_check_mark:		:warning: [2]
Mac [3]	:white_check_mark:	:white_check_mark:	:warning: [2]
Window			:white_check_mark:

Limitations:

• [1] If the app contains native dependency, it can only be compiled on the targeted platform.
• [2] Linux and macOS are unable to build Windows Appx packages for Windows Store.
• [3] All required system dependencies, except rpm, will be downloaded automatically on demand. RPM can be installed with brew. (macOS Sierra 10.12+)

The example below enables multi-platform build for all OS and uses the default build configurations.

{
  "electron": {
    "linux": {},
    "mac": {},
    "windows": {}
  }
}

Signing Configurations

macOS Signing

There are three types of signing targets. (debug, release, and store). Each section has the following properties:

key	description
entitlements	String path value to entitlements file.
entitlementsInherit	String path value to the entitlements file which inherits the security settings.
identity	String value of the name of the certificate.
requirements	String path value of requirements file. :warning: This is not available for the mas (store) signing configurations.
provisioningProfile	String path value of the provisioning profile.

Example Config:

{
  "electron": {
    "mac": {
      "package": [
        "dmg",
        "mas",
        "mas-dev",
      ],
      "signing": {
        "release": {
          "identity": "APACHE CORDOVA (TEAMID)",
          "provisioningProfile": "release.mobileprovision"
        }
      }
    }
  }
}

For macOS signing, there are a few exceptions to how the signing information is used. By default, all packages with the exception of mas and mas-dev, use the debug and release signing configurations.

Using the example config above, let's go over some use cases to better understand the exceptions.

Use Case 1:

$ cordova build electron --debug

The command above will:

• Generate a dmg build and mas-dev build using the debug signing configurations.
• Ignore the mas target package.

Use Case 2:

$ cordova build electron --release

The command above will:

• Generate a dmg build using the release config.
• Generate a mas build using the store config.
• Ignore the mas-dev target package.

Windows Signing

The signing information is comprised of two types. (debug, release). Each section has the following properties:

key	description
certificateFile	String path to the certificate file.
certificatePassword	String value of the certificate file's password. Alternative: The password can be set on the environment variable CSC_KEY_PASSWORD.
certificateSubjectName	String value of the signing certificate's subject. :warning: Required for EV Code Signing and requires Windows
certificateSha1	String value of the SHA1 hash of the signing certificate. :warning: Requires Windows
signingHashAlgorithms	Collection of singing algorithms to be used. (sha1, sha256) :warning: AppX builds only support sha256
additionalCertificateFile	String path to the additional certificate files.

Example Config:

{
  "electron": {
    "windows": {
      "package": [
        "nsis"
      ],
      "signing": {
        "release": {
          "certificateFile": "path_to_files",
          "certificatePassword": "password"
        }
      }
    }
  }
}

Linux Signing

There are not signing requirements for Linux builds.

Plugins

All browser-based plugins are usable with the Electron platform.

When adding a plugin, if the plugin supports both the electron and browser platform, the electron portion will be used. If the plugin misses electron, but contains the browser implementation, it will fall back on the browser implementation.

Internally, Electron is using Chromium (Chrome) as its web view. Some plugins may have conditions written specifically for each different browser. In this case, it may affect the behavior from what is intended. Since Electron may support feature that the browser does not, these plugins would possibly need to be updated for the electron platform.