update-electron-app

A drop-in module that adds autoUpdating capabilities to Electron apps

Supports multiple update sources:

• The free and open-source update.electronjs.org service.
• Static file storage E.g. S3, Google Cloud Storage, etc.

Requirements

Before using this module, make sure your Electron app meets these criteria:

• Your app runs on macOS or Windows
• Your builds are code signed (macOS only)
• If using update.electronjs.org
  • Your app has a public GitHub repository
  • Your builds are published to GitHub Releases
• If using static file storage
  • Your builds are published to S3 or other similar static file host using a tool like @electron-forge/publisher-s3

Installation

npm i update-electron-app

Usage

With update.electronjs.org

Drop this anywhere in your main process:

const { updateElectronApp } = require('update-electron-app')
updateElectronApp()

By default your repository URL is found in your app's package.json file.

You can also specify custom options:

const { updateElectronApp, UpdateSourceType } = require('update-electron-app')
updateElectronApp({
  updateSource: {
    type: UpdateSourceType.ElectronPublicUpdateService,
    repo: 'github-user/repo'
  },
  updateInterval: '1 hour',
  logger: require('electron-log')
})

With static file storage

const { updateElectronApp, UpdateSourceType } = require('update-electron-app')
updateElectronApp({
  updateSource: {
    type: UpdateSourceType.StaticStorage,
    baseUrl: `https://my-bucket.s3.amazonaws.com/my-app-updates/${process.platform}/${process.arch}`
  }
})

What happens?

Once you've called updateElectronApp as documented above, that's it! Here's what happens by default:

• Your app will check for updates at startup, then every ten minutes. This interval is configurable.
• No need to wait for your app's ready event; the module figures that out.
• If an update is found, it will automatically be downloaded in the background.
• When an update is finished downloading, a dialog is displayed allowing the user to restart the app now or later.

API

update(options)

Additional Options:

• updateInterval String (optional) - How frequently to check for updates. Defaults to 10 minutes. Minimum allowed interval is 5 minutes. This is a human readable interval supported by the ms module
• logger Object (optional) - A custom logger object that defines a log function. Defaults to console. See electron-log, a module that aggregates logs from main and renderer processes into a single file.
• notifyUser Boolean (optional) - Defaults to true. When enabled the user will be prompted to apply the update immediately after download.

Return value

updateElectronApp returns an object with a stopUpdates function that stops the periodic update checks:

const { updateElectronApp } = require('update-electron-app')
const { stopUpdates } = updateElectronApp()

// Later, when you no longer want to check for updates:
stopUpdates()

stopUpdates is safe to call at any time, including before the app is ready or on platforms where updates aren't supported. Calling it more than once has no additional effect.

FAQ

What kinds of assets do I need to build?

For macOS, you'll need to build a .zip file. Use electron-forge or electron-installer-zip to package your app as a zip.

For Windows, you'll need to build a .exe and .nupkg files with electron-forge or electron-winstaller.

For Windows auto-updates to work, make sure every GitHub Release also has the following Squirrel.Windows assets attached, otherwise the update will silently fail:

• RELEASES - the manifest that Squirrel reads to discover available updates
• *-full.nupkg - the full update package
• *.exe - the installer
• *-delta.nupkg - optional, smaller delta packages used to speed up updates when present

Why is my app launching multiple times?

On Windows, extra app launches indicate that your app isn't handling the Squirrel.Windows startup events (such as install, update, and uninstall) that fire during these operations. You can use the electron-squirrel-startup module to handle these events and avoid the unwanted launches.

Can I use this module by uploading my private app's builds to a public GitHub repository?

Yes :)

I want to manually upload my builds to a static storage solution, where do I put them?

If you publish your builds manually ensure the file structure is:

• **/{platform}/{arch}/{artifact}

For example that means that these files should exist:

• **/win32/x64/RELEASES
• **/darwin/arm64/RELEASES.json
• **/darwin/arm64/My App v1.0.0.zip (or something similar)
• ...

How does this module handle GitHub release states?

If using the public update service, the https://update.electronjs.org server handles release fetching logic. Only releases that have valid SemVer tags and are not marked as draft or pre-release will be collected by the update service.

The latest release returned by the repos/{owner}/{repo}/releases GitHub API containing all requisite binaries will be the update target.

License

MIT