W3cubDocs

/Cordova 9

Electron Platform Guide

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

System Requirements

Linux

Python version 2.7.x. It is recommended to check your Python version since some distributions like CentOS 6.x still use Python 2.6.x.

Mac

Python version 2.7.x with support for TLS 1.2.
Xcode, the IDE for macOS, comes bundled with necessary software development tools to code signing and compiling native code for macOS. Version 8.2.1 or higher.
RedHat Build Support
- Homebrew, one of the available macOS package managers, is used for installing additional tools and dependencies. Homebrew is 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

Python version 2.7.10 or higher.
PowerShell, for Windows 7 users, must be at version 3.0 or greater for app signing.
Debugging Tools for Windows is a toolkit for enhancing debug capabilities. It is recommended to install with the Windows SDK 10.0.15063.468.

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 --nobuild flag to disable the build process when previewing.

cordova run electron --nobuild

Build a Project

Debug Builds

cordova build electron
cordova build electron --debug

Release Builds

cordova build electron --release

Customizing the Application's Window Options

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

Working with a Cordova project, it is recommended to create an Electron settings file within the project's root directory, and set its the relative path in the preference option ElectronSettingsFilePath, in the config.xml file.

Example config.xml:

<platform name="electron">
    <preference name="ElectronSettingsFilePath" value="res/electron/settings.json" />
</platform>

To override or set any BrowserWindow options, in this file the options are added to the browserWindow property.

Example res/electron/settings.json:

{
    "browserWindow": { ... }
}

How to Set the Window's Default Size

By default, the width is set to 800 and the height set to 600. This can be overridden by setting the width and height property.

Example:

{
    "browserWindow": {
        "width": 1024,
        "height": 768
    }
}

How to Disable the Window From Being Resizable

Setting the resizable flag property, you can disable the user's ability to resize your application's window.

Example:

{
    "browserWindow": {
        "resizable": false
    }
}

How to Make the Window Fullscreen

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

Example:

{
    "browserWindow": {
        "fullscreen": true
    }
}

How to Support Node.js and Electron APIs

Set the nodeIntegration flag property to true. By default, this property flag is set to false to support popular libraries that insert symbols with the same names that Node.js and Electron already uses.

You can read more about this at Electron docs: I can not use jQuery/RequireJS/Meteor/AngularJS in Electron.

Example:

{
    "browserWindow": {
        "webPreferences": {
            "nodeIntegration": false
        }
    }
}

Customizing the Electron's Main Process

If it is necessary to customize the Electron's main process beyond the scope of the Electron's configuration settings, chances can be added directly to the cdv-electron-main.js file located in {PROJECT_ROOT_DIR}/platform/electron/platform_www/. This is the application's main process.

❗ However, it is not recommended to modify this file as the upgrade process for cordova-electron is to remove the old platform before adding the new version.

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 can be closed or opened manually with the debug build.

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	-	✅	-
mas	-	✅	-
mas-dev	✅	-	-
pkg	-	✅	-
7z	✅	✅	✅
zip	✅	✅	✅
tar.xz	✅	✅	✅
tar.lz	✅	✅	✅
tar.gz	✅	✅	✅
tar.bz2	✅	✅	✅
dir	✅	✅	✅
nsis	-	-	✅
nsis-web	-	-	✅
portable	-	-	✅
appx	-	-	✅ ^[1]
msi	-	-	✅
AppImage	✅	-	-
snap	✅	-	-
deb	✅	-	-
rpm	✅	-	-
freebsd	✅	-	-
pacman	✅	-	-
p5p	✅	-	-
apk	✅	-	-

[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.

❗ 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 an x64 dmg package.

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

Multi-Platform Build Support

❗ 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	✅		❗ ^[2]
Mac ^[3]	✅	✅	❗ ^[2]
Window			✅

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. ❗ 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. ❗ Required for EV Code Signing and requires Windows
certificateSha1	String value of the SHA1 hash of the signing certificate. ❗ Requires Windows
signingHashAlgorithms	Collection of singing algorithms to be used. (`sha1`, `sha256`) ❗ 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 of 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.

© 2012, 2013, 2015 The Apache Software Foundation
Licensed under the Apache License 2.0.
https://cordova.apache.org/docs/en/9.x/guide/platforms/electron/index.html

Electron Platform Guide

System Requirements

Linux

Mac

Windows

Quick Start

Create a Project

Preview a Project

Build a Project

Customizing the Application's Window Options

How to Set the Window's Default Size

How to Disable the Window From Being Resizable

How to Make the Window Fullscreen

How to Support Node.js and Electron APIs

Customizing the Electron's Main Process

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

Adding a `package`

Setting the Package `arch`