Skip to content

electron.md

Latest commit

 

History

History
188 lines (108 loc) · 9.98 KB

electron.md

File metadata and controls

188 lines (108 loc) · 9.98 KB

Electron

Electron allows to build native application, that can be installed and run on Windows, macOS and Linux.

Table of contents

NPM scripts

  • npm run electron:dev

Run Electron in development mode, concurrently starts 3 processes with watch for changes: main (main Electron process), renderer (FE code) and Webpack for Electron (compiles main Electron process from TypeScript).

  • npm run electron:webpack

The main process code for Electron, which includes preload functionality, is written in TypeScript and is compiled using the webpack-electron.config.js configuration to generate JavaScript code.

  • npm run electron:build

Prepare renderer (FE code) build, compile Electron main process code, install and build native dependencies, is used before packaging or publishing.

  • npm run electron:package:staging

Create packages for macOS, Windows and Linux in dist-electron folders with APP_ENV as staging (allows to open DevTools, includes sourcemaps and does not minify built JavaScript code), can be used for manual distribution and testing packaged application.

  • npm run electron:release:production

Create packages for macOS, Windows and Linux in dist-electron folders with APP_ENV as production (disabled DevTools, minified built JavaScript code), publish release to GitHub, which allows supporting automatic updates. See GitHub release workflow for more info.

Code signing on MacOS

To sign the code of your application, follow these steps:

  • Install certificates to login folder of your Keychain.
  • Download and install Developer ID - G2 certificate from the Apple PKI page.
  • Under the Keychain application, go to the private key associated with your developer certificate. Then do key > Get Info > Access Control. Down there, make sure your application (Xcode) is in the list Always allow access by these applications and make sure Confirm before allowing access is turned on.
  • A valid and appropriate identity from your keychain will be automatically used when you publish your application.

More info in the official documentation.

Notarize on MacOS

Application notarization is done automatically in electron-builder module, which requires APPLE_ID and APPLE_APP_SPECIFIC_PASSWORD environment variables to be passed.

How to obtain app-specific password:

  • Sign in to appleid.apple.com.
  • In the "Sign-In and Security" section, select "App-Specific Passwords".
  • Select "Generate an app-specific password" or select the Add button, then follow the steps on your screen.

GitHub release

GitHub access token

In order to publish new release, you need to add GitHub access token to .env. Generate a GitHub access token by going to https://github.com/settings/tokens/new. The access token should have the repo scope/permission. Once you have the token, assign it to an environment variable:

# .env
GH_TOKEN="{YOUR_TOKEN_HERE}"

Publish settings

Publish configuration in electron-builder.yml config file allows to set GitHub repository owner/name.

Release workflow

  • Draft a new release on GitHub. Create new tag version with the value of version in your application package.json, and prefix it with v. “Release title” can be anything you want.

    For example, if your application package.json version is 1.0, your draft’s tag version would be v1.0.

  • Save draft release

  • Run npm run electron:publish, which will upload build artefacts to newly created release.

  • Once you are done, publish the release. GitHub will tag the latest commit.

Application updates

The application exposes the "Auto-Updates" feature, allowing users to customize their chosen approach for controlling application updates with 2 distinct ways:

  1. Auto-Updates are turned on (default behaviour):

This grants users the option to allow the application itself to take control of the update process and introduces two mechanisms for checking and facilitating the installation of new versions automatically:

  • Update of Web version — "Update" button is displayed, leading to simple reload with location.reload()
  • Update of Electron version — "Update" button is displayed, leading to full application reload, including download and installation of new version

In this case application is loaded from BASE_URL specified in GitHub repository variables (PRODUCTION_URL from config is taken by default).

  • Auto-Updates are turned off:

Involves the same mechanism to check for updates, but instead of reload/install, "Update" button leads to https://mytonwallet.app/get

In this case application is loaded from index.html file from Electron application build.

Checking for updates in Web version

In the Web version, the process of checking for a new version involves accessing the version.txt file through the {ENVIRONMENT_URL}/version.txt URL. Version in this file is automatically incremented using the postversion NPM script during release process.

The update check is performed by comparing the version available from {ENVIRONMENT_URL}/version.txt with the value from APP_VERSION variable, which is retrieved from the package.json file during the Webpack build process.

Checking for updates in Electron

The process of checking for updates in the Electron application relies on the electron builder Auto Updates mechanism.

To determine whether an Electron update is available, the {ENVIRONMENT_URL}/electronVersion.txt file is utilized.

Important: this file should be manually updated to match the version specified in the package.json before initiating a release. The version in electronVersion.txt should only be incremented if the release includes changes related to Electron. This includes updates to Electron dependencies, modifications in Electron assets, or changes in the src/electron or webpack-electron.config.ts files and folders.

Test scenarios

Testing of the "Auto-Updates" feature can be split into severals groups of scenarios

"Auto-Updates" feature is turned on (default scenario when user installs new application version manually)

  1. No application updates are available:

Prerequisites:

  • version in package.json and in ${ENVIRONMENT_URL}/version.txt files is the same
  • version in package.json and in ${ENVIRONMENT_URL}/electronVersion.txt.txt files is the same
  • no available releases in public repo with version above the one in the package.json file

Expected behaviour: "Update" button is not displayed

  1. Web application update available:

Prerequisites:

  • version in package.json is lower than the one in ${ENVIRONMENT_URL}/version.txt file
  • version in package.json and in ${ENVIRONMENT_URL}/electronVersion.txt.txt files is the same
  • no available releases in public repo with version above the one in the package.json file

Expected behaviour: "Update" button is visible, on click application content reloads, "Update" button disappears

  1. Electron application update available:

Prerequisites:

  • version in package.json and in ${ENVIRONMENT_URL}/version.txt files is the same
  • version in package.json is lower that the one is in ${ENVIRONMENT_URL}/electronVersion.txt.txt files
  • since version bump in electronVersion.txt file should be done right before release, there is a new available release in public repo with version above the one in the package.json file

Expected behaviour: "Update" button is visible in a few minutes after application start (update is being downloaded on the background), on click full application reload and update installation is happening

  1. Both updates are available:

Prerequisites:

  • version in package.json is lower than the one in ${ENVIRONMENT_URL}/version.txt file
  • version in package.json is lower that the one is in ${ENVIRONMENT_URL}/electronVersion.txt.txt files
  • since version bump in electronVersion.txt file should be done right before release, there is a new available release in public repo with version above the one in the package.json file

Expected behaviour: "Update" button is visible, on click full application reload and update installation is happening (electron update is in higher priority over Web update)

"Auto-Updates" feature is turned off

The same test scenarios as when "Auto-Updates" is turned on, but instead of reload/install, "Update" button leads to https://mytonwallet.app/get. Button will disapper only after new update is manually installed.

Toggling "Auto-Updates" feature

Toggle is located in Settings with "Enable Auto-Updates" name.

Expected behaviour: application content is being reloaded, application state clears, all settings and session are kept. In case "Update" button is displayed, it's logic changes depending on "Enable Auto-Updates" setting value.

User has version of application older that the one where Auto-Updates were introduced

Prerequisites:

  • Clear application data from the following folders:
# MacOS:
~/Library/Application Support/<Your App Name>

# Windows:
C:\Users\<Your Username>\AppData\Roaming\<Your App Name>

  • Install application with the version prior to the one, which includes "Auto-Updates" feature implemented and login

  • Download and install (manually or with "Update" button) new version with "Auto-Updates" feature

Expected behaviour: session and all settings are kept, "Enable Auto-Updates" is turned on in the Settings, "Update" button is not visible