Update Electron Docs (#997)
- Sync with cordova-electron repo DOCUMENTATION.md
diff --git a/www/docs/en/9.x/config_ref/images.md b/www/docs/en/9.x/config_ref/images.md
index 9916f54..73f711b 100644
--- a/www/docs/en/9.x/config_ref/images.md
+++ b/www/docs/en/9.x/config_ref/images.md
@@ -264,7 +264,7 @@
```xml
<platform name="electron">
- <icon src="res/electron/icon.png" />
+ <icon src="res/electron/icon.png" />
</platform>
```
@@ -272,8 +272,8 @@
```xml
<platform name="electron">
- <icon src="res/electron/app.png" target="app" />
- <icon src="res/electron/installer.png" target="installer" />
+ <icon src="res/electron/app.png" target="app" />
+ <icon src="res/electron/installer.png" target="installer" />
</platform>
```
@@ -281,16 +281,16 @@
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)
+- 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:
```xml
<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" />
+ <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>
```
\ No newline at end of file
diff --git a/www/docs/en/9.x/guide/platforms/electron/index.md b/www/docs/en/9.x/guide/platforms/electron/index.md
index d43342b..753d3b1 100644
--- a/www/docs/en/9.x/guide/platforms/electron/index.md
+++ b/www/docs/en/9.x/guide/platforms/electron/index.md
@@ -25,77 +25,79 @@
Electron is a framework that uses web technologies (HTML, CSS, and JS) to build cross-platform desktop applications.
-## Requirements and Support
+## 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.
+- **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.
+- **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**](https://brew.sh/)
+ - **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**](https://brew.sh/) command:
-* **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 will be needed to install RPM packaging dependencies. [**Brew Install Step**](https://brew.sh/)
-
- * **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**](https://brew.sh/) command:
-
- ```
- $ brew install rpm
+ ```bash
+ 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](https://www.electron.build/code-signing#windows).
-
-* **[Debugging Tools for Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/)** is a toolkit for enhancing debug capabilities. It is recommended to install with the **Windows SDK 10.0.15063.468**.
-
+- **Python** version 2.7.10 or higher.
+- **PowerShell**, for Windows 7 users, must be at version 3.0 or greater for [app signing](https://www.electron.build/code-signing#windows).
+- **[Debugging Tools for Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/)** 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
+```bash
+npm i -g cordova
+cordova create sampleApp
+cd sampleApp
+cordova platform add electron
```
-$ 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:_
+
+```bash
+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
+```bash
+cordova run electron --nobuild
```
### Build a Project
**Debug Builds**
-```
-$ cordova build electron
-$ cordova build electron --debug
+```bash
+cordova build electron
+cordova build electron --debug
```
**Release Builds**
-```
-$ cordova build electron --release
+```bash
+cordova build electron --release
```
-## Customizing Application Window
+## Customizing the Application's Window Options
Electron provides many options to manipulate the [`BrowserWindow`](https://electronjs.org/docs/api/browser-window). 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](https://electronjs.org/docs/api/browser-window#new-browserwindowoptions).
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`:**
+
```xml
<platform name="electron">
<preference name="ElectronSettingsFilePath" value="res/electron/settings.json" />
@@ -108,17 +110,17 @@
```json
{
- "browserWindow": { ... }
+ "browserWindow": { ... }
}
```
-### How to set the default window size?
+### 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:**
- ```json
+```json
{
"browserWindow": {
"width": 1024,
@@ -127,13 +129,13 @@
}
```
-### How to make the window not resizable?
+### 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.
+Setting the `resizable` flag property, you can disable the user's ability to resize your application's window.
- **Example:**
+**Example:**
- ```json
+```json
{
"browserWindow": {
"resizable": false
@@ -141,11 +143,12 @@
}
```
-#### How to make my window fullscreen?
+### How to Make the Window Fullscreen
Using the `fullscreen` flag property, you can force the application to launch in fullscreen.
**Example:**
+
```json
{
"browserWindow": {
@@ -154,29 +157,31 @@
}
```
-### How to support Node.js and Electron APIs?
+### 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.
+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](https://electronjs.org/docs/faq#i-can-not-use-jqueryrequirejsmeteorangularjs-in-electron).
-
+> You can read more about this at Electron docs: [I can not use jQuery/RequireJS/Meteor/AngularJS in Electron](https://electronjs.org/docs/faq#i-can-not-use-jqueryrequirejsmeteorangularjs-in-electron).
+
**Example:**
- ```json
+```json
{
"browserWindow": {
- "nodeIntegration": true
+ "webPreferences": {
+ "nodeIntegration": false
+ }
}
}
```
-## Customizing Main Process
+## 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.
+> ❗ 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
+## 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.
@@ -192,20 +197,20 @@
| Package | Arch |
| ------- | :---: |
-| tar.gz | x64 |
+| tar.gz | x64 |
**Mac**
| Package | Arch |
| ------- | :---: |
-| dmg | x64 |
-| zip | x64 |
+| dmg | x64 |
+| zip | x64 |
**Windows**
| Package | Arch |
| ------- | :---: |
-| nsis | x64 |
+| nsis | x64 |
### Customizing Build Configurations
@@ -213,9 +218,9 @@
**Example Config Structure**
-```
+```json
{
- "electron": {}
+ "electron": {}
}
```
@@ -223,22 +228,23 @@
**Example Config Structure with Each Platform**
-```
+```json
{
- "electron": {
- linux: {},
- mac: {},
- windows: {}
- }
+ "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](#signing-configurations) for more information.
+
+- `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](#signing-configurations) for more information.
Any properties that are undefined will fallback to default values.
@@ -248,77 +254,75 @@
The configuration example below will generate `tar.gz`, `dmg` and `zip` packages for macOS.
-```
+```json
{
- "electron": {
- "mac": {
- "package": [
- "dmg",
- "tar.gz",
- "zip"
- ]
+ "electron": {
+ "mac": {
+ "package": [
+ "dmg",
+ "tar.gz",
+ "zip"
+ ]
+ }
}
- }
}
```
**Available Packages by Operating System**
-| Package Type | Linux | macOS | Windows |
-| ------------ | :----------------: | :----------------: | :-----------------------------------: |
-| default | - | `dmg`<br />`zip` | - |
-| dmg | - | ✔ | - |
-| mas | - | ✔ | - |
-| mas-dev | ✔ | - | - |
-| pkg | - | ✔ | - |
-| 7z | ✔ | ✔ | ✔ |
-| zip | ✔ | ✔ | ✔ |
-| tar.xz | ✔ | ✔ | ✔ |
-| tar.lz | ✔ | ✔ | ✔ |
-| tar.gz | ✔ | ✔ | ✔ |
-| tar.bz2 | ✔ | ✔ | ✔ |
-| dir | ✔ | ✔ | ✔ |
-| nsis | - | - | ✔ |
-| nsis-web | - | - | ✔ |
-| portable | - | - | ✔ |
-| appx | - | - | ✔ <sup>**[1]**</sup> |
-| msi | - | - | ✔ |
-| AppImage | ✔ | - | - |
-| snap | ✔ | - | - |
-| deb | ✔ | - | - |
-| rpm | ✔ | - | - |
-| freebsd | ✔ | - | - |
-| pacman | ✔ | - | - |
-| p5p | ✔ | - | - |
-| apk | ✔ | - | - |
+| Package Type | Linux | macOS | Windows |
+| ------------ | :-----: | :--------------: | :------------------------: |
+| default | - | `dmg`<br />`zip` | - |
+| dmg | - | ✅ | - |
+| mas | - | ✅ | - |
+| mas-dev | ✅ | - | - |
+| pkg | - | ✅ | - |
+| 7z | ✅ | ✅ | ✅ |
+| zip | ✅ | ✅ | ✅ |
+| tar.xz | ✅ | ✅ | ✅ |
+| tar.lz | ✅ | ✅ | ✅ |
+| tar.gz | ✅ | ✅ | ✅ |
+| tar.bz2 | ✅ | ✅ | ✅ |
+| dir | ✅ | ✅ | ✅ |
+| nsis | - | - | ✅ |
+| nsis-web | - | - | ✅ |
+| portable | - | - | ✅ |
+| appx | - | - | ✅ <sup>**[1]**</sup> |
+| msi | - | - | ✅ |
+| AppImage | ✅ | - | - |
+| snap | ✅ | - | - |
+| deb | ✅ | - | - |
+| rpm | ✅ | - | - |
+| freebsd | ✅ | - | - |
+| pacman | ✅ | - | - |
+| p5p | ✅ | - | - |
+| apk | ✅ | - | - |
-* **[1]** Only Window 10 can build AppX packages.
+- **[1]** Only Window 10 can build AppX packages.
-#### Setting the package `arch`
+#### 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](https://github.com/electron/electron/releases/) to identify valid combinations. For example, macOS (Darwin) only supports x64.
**Available Arch**
-* ia32
-* x64
-* armv71
-* arm64
+- ia32
+- x64
+- armv71
+- arm64
The example above will generate an `x64` `dmg` package.
-```
+```json
{
- "electron": {
- "mac": {
- "package": [
- "dmg"
- ],
- "arch": ["x64"]
+ "electron": {
+ "mac": {
+ "package": [ "dmg" ],
+ "arch": [ "x64" ]
+ }
}
- }
}
```
@@ -330,26 +334,27 @@
The matrix below shows each host OS and for which platforms they are capable of building applications.
-| Host <sup>**[1]**</sup> | Linux | Mac | Window |
-| ----------------------- | :----------------: | :----------------: | :--------------------------: |
-| Linux | ✔ | - | ❗ <sup>**[2]**</sup> |
-| Mac <sup>**[3]**</sup> | ✔ | ✔ | ❗ <sup>**[2]**</sup> |
-| Window | - | - | ✔ |
+| Host <sup>**[1]**</sup> | Linux | Mac | Window |
+| ----------------------- | :-----: | :-----: | :-------------------------: |
+| Linux | ✅ | | ❗ <sup>**[2]**</sup> |
+| Mac <sup>**[3]**</sup> | ✅ | ✅ | ❗ <sup>**[2]**</sup> |
+| 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 using brew. (macOS Sierra 10.12+)](https://www.electron.build/multi-platform-build#macos)
+
+- **[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+)](https://www.electron.build/multi-platform-build#macos)
The example below enables multi-platform build for all OS and uses the default build configurations.
-```
+```json
{
- "electron": {
- "linux": {},
- "mac": {},
- "windows": {}
- }
+ "electron": {
+ "linux": {},
+ "mac": {},
+ "windows": {}
+ }
}
```
@@ -357,36 +362,35 @@
### 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. |
+| 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](https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/RequirementLang/RequirementLang.html) | String path value of requirements file. <br /><br />❗ This is not available for the `mas` (store) signing configurations. |
-| provisioningProfile | String path value of the provisioning profile. |
+| provisioningProfile | String path value of the provisioning profile. |
**Example Config:**
-```
+```json
{
- "electron": {
- "mac": {
- "package": [
- "dmg",
- "mas",
- "mas-dev",
- ],
- "signing": {
- "release": {
- "identity": "APACHE CORDOVA (TEAMID)",
- "provisioningProfile": "release.mobileprovision"
+ "electron": {
+ "mac": {
+ "package": [
+ "dmg",
+ "mas",
+ "mas-dev"
+ ],
+ "signing": {
+ "release": {
+ "identity": "APACHE CORDOVA (TEAMID)",
+ "provisioningProfile": "release.mobileprovision"
+ }
+ }
}
- }
}
- }
}
```
@@ -397,25 +401,26 @@
**Use Case 1:**
-```
-$ cordova build electron --debug
+```bash
+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:**
+- Generate a `dmg` build and `mas-dev` build using the `debug` signing configurations.
+- Ignore the `mas` target package.
-```
-$ cordova build electron --release
+*Use Case 2:*
+
+```bash
+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.
+- Generate a `dmg` build using the `release` config.
+- Generate a `mas` build using the `store` config.
+- Ignore the `mas-dev` target package.
### Windows Signing
@@ -432,21 +437,19 @@
**Example Config:**
-```
+```json
{
- "electron": {
- "windows": {
- "package": [
- "nsis"
- ],
- "signing": {
- "release": {
- "certificateFile": "path_to_files",
- "certificatePassword": "password"
+ "electron": {
+ "windows": {
+ "package": [ "nsis" ],
+ "signing": {
+ "release": {
+ "certificateFile": "path_to_files",
+ "certificatePassword": "password"
+ }
+ }
}
- }
}
- }
}
```
diff --git a/www/docs/en/dev/config_ref/images.md b/www/docs/en/dev/config_ref/images.md
index 9916f54..73f711b 100644
--- a/www/docs/en/dev/config_ref/images.md
+++ b/www/docs/en/dev/config_ref/images.md
@@ -264,7 +264,7 @@
```xml
<platform name="electron">
- <icon src="res/electron/icon.png" />
+ <icon src="res/electron/icon.png" />
</platform>
```
@@ -272,8 +272,8 @@
```xml
<platform name="electron">
- <icon src="res/electron/app.png" target="app" />
- <icon src="res/electron/installer.png" target="installer" />
+ <icon src="res/electron/app.png" target="app" />
+ <icon src="res/electron/installer.png" target="installer" />
</platform>
```
@@ -281,16 +281,16 @@
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)
+- 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:
```xml
<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" />
+ <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>
```
\ No newline at end of file
diff --git a/www/docs/en/dev/guide/platforms/electron/index.md b/www/docs/en/dev/guide/platforms/electron/index.md
index d43342b..753d3b1 100644
--- a/www/docs/en/dev/guide/platforms/electron/index.md
+++ b/www/docs/en/dev/guide/platforms/electron/index.md
@@ -25,77 +25,79 @@
Electron is a framework that uses web technologies (HTML, CSS, and JS) to build cross-platform desktop applications.
-## Requirements and Support
+## 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.
+- **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.
+- **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**](https://brew.sh/)
+ - **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**](https://brew.sh/) command:
-* **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 will be needed to install RPM packaging dependencies. [**Brew Install Step**](https://brew.sh/)
-
- * **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**](https://brew.sh/) command:
-
- ```
- $ brew install rpm
+ ```bash
+ 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](https://www.electron.build/code-signing#windows).
-
-* **[Debugging Tools for Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/)** is a toolkit for enhancing debug capabilities. It is recommended to install with the **Windows SDK 10.0.15063.468**.
-
+- **Python** version 2.7.10 or higher.
+- **PowerShell**, for Windows 7 users, must be at version 3.0 or greater for [app signing](https://www.electron.build/code-signing#windows).
+- **[Debugging Tools for Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/)** 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
+```bash
+npm i -g cordova
+cordova create sampleApp
+cd sampleApp
+cordova platform add electron
```
-$ 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:_
+
+```bash
+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
+```bash
+cordova run electron --nobuild
```
### Build a Project
**Debug Builds**
-```
-$ cordova build electron
-$ cordova build electron --debug
+```bash
+cordova build electron
+cordova build electron --debug
```
**Release Builds**
-```
-$ cordova build electron --release
+```bash
+cordova build electron --release
```
-## Customizing Application Window
+## Customizing the Application's Window Options
Electron provides many options to manipulate the [`BrowserWindow`](https://electronjs.org/docs/api/browser-window). 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](https://electronjs.org/docs/api/browser-window#new-browserwindowoptions).
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`:**
+
```xml
<platform name="electron">
<preference name="ElectronSettingsFilePath" value="res/electron/settings.json" />
@@ -108,17 +110,17 @@
```json
{
- "browserWindow": { ... }
+ "browserWindow": { ... }
}
```
-### How to set the default window size?
+### 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:**
- ```json
+```json
{
"browserWindow": {
"width": 1024,
@@ -127,13 +129,13 @@
}
```
-### How to make the window not resizable?
+### 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.
+Setting the `resizable` flag property, you can disable the user's ability to resize your application's window.
- **Example:**
+**Example:**
- ```json
+```json
{
"browserWindow": {
"resizable": false
@@ -141,11 +143,12 @@
}
```
-#### How to make my window fullscreen?
+### How to Make the Window Fullscreen
Using the `fullscreen` flag property, you can force the application to launch in fullscreen.
**Example:**
+
```json
{
"browserWindow": {
@@ -154,29 +157,31 @@
}
```
-### How to support Node.js and Electron APIs?
+### 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.
+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](https://electronjs.org/docs/faq#i-can-not-use-jqueryrequirejsmeteorangularjs-in-electron).
-
+> You can read more about this at Electron docs: [I can not use jQuery/RequireJS/Meteor/AngularJS in Electron](https://electronjs.org/docs/faq#i-can-not-use-jqueryrequirejsmeteorangularjs-in-electron).
+
**Example:**
- ```json
+```json
{
"browserWindow": {
- "nodeIntegration": true
+ "webPreferences": {
+ "nodeIntegration": false
+ }
}
}
```
-## Customizing Main Process
+## 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.
+> ❗ 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
+## 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.
@@ -192,20 +197,20 @@
| Package | Arch |
| ------- | :---: |
-| tar.gz | x64 |
+| tar.gz | x64 |
**Mac**
| Package | Arch |
| ------- | :---: |
-| dmg | x64 |
-| zip | x64 |
+| dmg | x64 |
+| zip | x64 |
**Windows**
| Package | Arch |
| ------- | :---: |
-| nsis | x64 |
+| nsis | x64 |
### Customizing Build Configurations
@@ -213,9 +218,9 @@
**Example Config Structure**
-```
+```json
{
- "electron": {}
+ "electron": {}
}
```
@@ -223,22 +228,23 @@
**Example Config Structure with Each Platform**
-```
+```json
{
- "electron": {
- linux: {},
- mac: {},
- windows: {}
- }
+ "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](#signing-configurations) for more information.
+
+- `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](#signing-configurations) for more information.
Any properties that are undefined will fallback to default values.
@@ -248,77 +254,75 @@
The configuration example below will generate `tar.gz`, `dmg` and `zip` packages for macOS.
-```
+```json
{
- "electron": {
- "mac": {
- "package": [
- "dmg",
- "tar.gz",
- "zip"
- ]
+ "electron": {
+ "mac": {
+ "package": [
+ "dmg",
+ "tar.gz",
+ "zip"
+ ]
+ }
}
- }
}
```
**Available Packages by Operating System**
-| Package Type | Linux | macOS | Windows |
-| ------------ | :----------------: | :----------------: | :-----------------------------------: |
-| default | - | `dmg`<br />`zip` | - |
-| dmg | - | ✔ | - |
-| mas | - | ✔ | - |
-| mas-dev | ✔ | - | - |
-| pkg | - | ✔ | - |
-| 7z | ✔ | ✔ | ✔ |
-| zip | ✔ | ✔ | ✔ |
-| tar.xz | ✔ | ✔ | ✔ |
-| tar.lz | ✔ | ✔ | ✔ |
-| tar.gz | ✔ | ✔ | ✔ |
-| tar.bz2 | ✔ | ✔ | ✔ |
-| dir | ✔ | ✔ | ✔ |
-| nsis | - | - | ✔ |
-| nsis-web | - | - | ✔ |
-| portable | - | - | ✔ |
-| appx | - | - | ✔ <sup>**[1]**</sup> |
-| msi | - | - | ✔ |
-| AppImage | ✔ | - | - |
-| snap | ✔ | - | - |
-| deb | ✔ | - | - |
-| rpm | ✔ | - | - |
-| freebsd | ✔ | - | - |
-| pacman | ✔ | - | - |
-| p5p | ✔ | - | - |
-| apk | ✔ | - | - |
+| Package Type | Linux | macOS | Windows |
+| ------------ | :-----: | :--------------: | :------------------------: |
+| default | - | `dmg`<br />`zip` | - |
+| dmg | - | ✅ | - |
+| mas | - | ✅ | - |
+| mas-dev | ✅ | - | - |
+| pkg | - | ✅ | - |
+| 7z | ✅ | ✅ | ✅ |
+| zip | ✅ | ✅ | ✅ |
+| tar.xz | ✅ | ✅ | ✅ |
+| tar.lz | ✅ | ✅ | ✅ |
+| tar.gz | ✅ | ✅ | ✅ |
+| tar.bz2 | ✅ | ✅ | ✅ |
+| dir | ✅ | ✅ | ✅ |
+| nsis | - | - | ✅ |
+| nsis-web | - | - | ✅ |
+| portable | - | - | ✅ |
+| appx | - | - | ✅ <sup>**[1]**</sup> |
+| msi | - | - | ✅ |
+| AppImage | ✅ | - | - |
+| snap | ✅ | - | - |
+| deb | ✅ | - | - |
+| rpm | ✅ | - | - |
+| freebsd | ✅ | - | - |
+| pacman | ✅ | - | - |
+| p5p | ✅ | - | - |
+| apk | ✅ | - | - |
-* **[1]** Only Window 10 can build AppX packages.
+- **[1]** Only Window 10 can build AppX packages.
-#### Setting the package `arch`
+#### 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](https://github.com/electron/electron/releases/) to identify valid combinations. For example, macOS (Darwin) only supports x64.
**Available Arch**
-* ia32
-* x64
-* armv71
-* arm64
+- ia32
+- x64
+- armv71
+- arm64
The example above will generate an `x64` `dmg` package.
-```
+```json
{
- "electron": {
- "mac": {
- "package": [
- "dmg"
- ],
- "arch": ["x64"]
+ "electron": {
+ "mac": {
+ "package": [ "dmg" ],
+ "arch": [ "x64" ]
+ }
}
- }
}
```
@@ -330,26 +334,27 @@
The matrix below shows each host OS and for which platforms they are capable of building applications.
-| Host <sup>**[1]**</sup> | Linux | Mac | Window |
-| ----------------------- | :----------------: | :----------------: | :--------------------------: |
-| Linux | ✔ | - | ❗ <sup>**[2]**</sup> |
-| Mac <sup>**[3]**</sup> | ✔ | ✔ | ❗ <sup>**[2]**</sup> |
-| Window | - | - | ✔ |
+| Host <sup>**[1]**</sup> | Linux | Mac | Window |
+| ----------------------- | :-----: | :-----: | :-------------------------: |
+| Linux | ✅ | | ❗ <sup>**[2]**</sup> |
+| Mac <sup>**[3]**</sup> | ✅ | ✅ | ❗ <sup>**[2]**</sup> |
+| 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 using brew. (macOS Sierra 10.12+)](https://www.electron.build/multi-platform-build#macos)
+
+- **[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+)](https://www.electron.build/multi-platform-build#macos)
The example below enables multi-platform build for all OS and uses the default build configurations.
-```
+```json
{
- "electron": {
- "linux": {},
- "mac": {},
- "windows": {}
- }
+ "electron": {
+ "linux": {},
+ "mac": {},
+ "windows": {}
+ }
}
```
@@ -357,36 +362,35 @@
### 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. |
+| 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](https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/RequirementLang/RequirementLang.html) | String path value of requirements file. <br /><br />❗ This is not available for the `mas` (store) signing configurations. |
-| provisioningProfile | String path value of the provisioning profile. |
+| provisioningProfile | String path value of the provisioning profile. |
**Example Config:**
-```
+```json
{
- "electron": {
- "mac": {
- "package": [
- "dmg",
- "mas",
- "mas-dev",
- ],
- "signing": {
- "release": {
- "identity": "APACHE CORDOVA (TEAMID)",
- "provisioningProfile": "release.mobileprovision"
+ "electron": {
+ "mac": {
+ "package": [
+ "dmg",
+ "mas",
+ "mas-dev"
+ ],
+ "signing": {
+ "release": {
+ "identity": "APACHE CORDOVA (TEAMID)",
+ "provisioningProfile": "release.mobileprovision"
+ }
+ }
}
- }
}
- }
}
```
@@ -397,25 +401,26 @@
**Use Case 1:**
-```
-$ cordova build electron --debug
+```bash
+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:**
+- Generate a `dmg` build and `mas-dev` build using the `debug` signing configurations.
+- Ignore the `mas` target package.
-```
-$ cordova build electron --release
+*Use Case 2:*
+
+```bash
+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.
+- Generate a `dmg` build using the `release` config.
+- Generate a `mas` build using the `store` config.
+- Ignore the `mas-dev` target package.
### Windows Signing
@@ -432,21 +437,19 @@
**Example Config:**
-```
+```json
{
- "electron": {
- "windows": {
- "package": [
- "nsis"
- ],
- "signing": {
- "release": {
- "certificateFile": "path_to_files",
- "certificatePassword": "password"
+ "electron": {
+ "windows": {
+ "package": [ "nsis" ],
+ "signing": {
+ "release": {
+ "certificateFile": "path_to_files",
+ "certificatePassword": "password"
+ }
+ }
}
- }
}
- }
}
```
