Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท Packaging and Auto-update

Auto-update: Shipping New Versions to Users

Understand how Electron apps update themselves: the autoUpdater events, update servers and GitHub Releases, semantic versions, staged rollouts, update UX and safe failure handling.

The day after you release, you find a bug. Without auto-update, every user keeps the broken version until they happen to download a new one. With auto-update, the app notices a newer release, downloads it in the background, and offers to restart. Users stay on a recent, patched version, and you can fix security problems in days instead of months.

Electron provides the low-level autoUpdater module, and the community built layers on top: update-electron-app (tiny setup for open source apps on GitHub Releases) and electron-updater (part of electron-builder, with many providers). This lesson explains the moving parts, the events you handle, and the design decisions around versions, rollouts and failure.

The flow

sequenceDiagram
  participant A as Running app (v1.2.0)
  participant S as Update server or GitHub Releases
  A->>S: Is there something newer than 1.2.0?
  S-->>A: Yes, 1.3.0 with download URL
  A->>S: Download update
  S-->>A: Signed package
  A->>A: Verify signature, stage update
  A->>A: User clicks Restart
  A->>A: Quit and install, launch v1.3.0

The update is verified before it is installed, and only applied when the app quits.

Key facts:

  • Updates must be signed on macOS and Windows (see Installers and Code Signing); the OS refuses an unsigned replacement.
  • On Windows, the Squirrel format (Forge's default maker) supports autoUpdater; NSIS works through electron-updater. On macOS the ZIP artifact is used for updates. Linux has no built-in autoUpdater; AppImage can use electron-updater, and deb or rpm users update through their package manager.
  • Dev builds do not update. Test with a packaged and signed build.

The simplest setup

For apps whose releases are on GitHub, update-electron-app is three lines:

JavaScript
import { updateElectronApp } from 'update-electron-app';

updateElectronApp({
  updateInterval: '1 hour',
  notifyUser: true,        // shows a native dialog when an update is downloaded
});

It checks GitHub's public update service for releases matching your repository and platform, downloads them, and prompts the user to restart.

Using autoUpdater directly

For full control, use the module itself and handle its events:

JavaScript
import { autoUpdater, dialog } from 'electron';

autoUpdater.setFeedURL({ url: `https://updates.example.com/${process.platform}/${app.getVersion()}` });

autoUpdater.on('checking-for-update', () => log('checking'));
autoUpdater.on('update-available', () => log('downloading'));
autoUpdater.on('update-not-available', () => log('up to date'));
autoUpdater.on('error', (err) => log('update error', err.message));

autoUpdater.on('update-downloaded', async (_e, notes, releaseName) => {
  const { response } = await dialog.showMessageBox({
    type: 'info',
    buttons: ['Restart now', 'Later'],
    message: `Version ${releaseName} is ready`,
    detail: notes,
  });
  if (response === 0) autoUpdater.quitAndInstall();
});

setInterval(() => autoUpdater.checkForUpdates(), 60 * 60 * 1000);
autoUpdater.checkForUpdates();

The update server's contract is simple: when asked for updates for version X, respond 204 No Content if X is current, or 200 with JSON (url, name, notes, pub_date) pointing to the newer release. Services such as GitHub Releases, Hazel, Nuts or your own small endpoint can implement it.

Semantic versions and the decision

Whatever server you use, the heart of the matter is comparing versions. Use semantic versioning: MAJOR.MINOR.PATCH, with an optional pre-release such as 1.4.0-beta.2. A pre-release is older than the same release without the suffix.

This stand-in implements the core server decision: given the user's version and the list of published releases, pick the newest eligible one. It handles pre-release channels and a minimum-supported version.

Node.js Choosing the right update

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the last line: a user on beta 2 who switches to the stable channel is offered the final 1.4.0, because a pre-release is older than its release.

Staged rollouts

A buggy update that reaches everyone at once is a disaster. A staged rollout releases to a percentage of users first. The usual trick is to hash a stable user or install id into a bucket from 0 to 99, and only offer the update when the bucket is below the current rollout percentage. Raise the percentage as the crash reports stay quiet; set it to 0 to halt.

Node.js Percentage rollout by hashed install id

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Because the bucket depends on the version and id, the same users do not always get every release first, and a user never flips between "eligible" and "not eligible" at a given percentage.

A good update experience

  • Never interrupt work. Download silently, then offer "Restart now" or "Later". Apply on next launch if they choose later.
  • Show release notes in the dialog or a changelog link.
  • Handle failure quietly. The error event fires for offline users and server hiccups. Log it, retry at the next interval, and do not show an error dialog for a background check.
  • Provide a manual check in the Help menu; it shows "You are up to date" or errors explicitly.
  • Mind the first launch after update. Run settings migrations (App Data and Settings) at startup.
  • Keep old versions working. If you change the server API, remember that users on old versions still call the old endpoint.

Updates are a security surface

An update channel is a remote code execution channel by design. Protect it: serve updates over https only, sign every release with your certificate, keep signing keys off developer laptops, and make sure the update server's credentials are not the same as your website's. electron-updater can additionally verify a publisher name against the signature.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What status should a simple update server return when the client is already up to date?

    autoUpdater treats 204 as 'no update available'. A 200 response must contain the JSON describing a newer release.
  2. 2. Which version is newest according to semantic versioning?

    A pre-release sorts before the matching release, so 1.4.0 is newer than every 1.4.0-something.
  3. 3. Why hash the install id when doing a staged rollout?

    A deterministic bucket per install is consistent between checks and spreads releases across different users.
  4. 4. How should a background update check that fails because the user is offline be handled?

    Offline is normal. Interrupting the user would be annoying; a manual 'Check for updates' can report errors explicitly.

Summary

  • Auto-update needs a signed, packaged build; Linux relies on package managers or AppImage tooling.
  • update-electron-app is the quick path for GitHub Releases; autoUpdater and electron-updater give full control.
  • Handle update-downloaded with a non-intrusive prompt and quitAndInstall.
  • Use semantic versions with pre-release channels and staged rollouts keyed by a hashed install id.
  • Treat the update channel as a security-critical path: https, signing and protected keys.

Next: Testing Electron Apps