auto-update & packaging

16 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

autoUpdater module availability and process

The autoUpdater module enables apps to automatically update themselves and runs in the Main process. It is an EventEmitter. Only macOS and Windows are supported; there is no built-in support for auto-updater on Linux.

macOS autoUpdater built on Squirrel.Mac

On macOS, the autoUpdater module is built upon Squirrel.Mac, requiring no special setup. The application must be code-signed for automatic updates on macOS, as this is a requirement of Squirrel.Mac. App Transport Security (ATS) applies to all requests made during the update process; apps needing to disable ATS can add the NSAllowsArbitraryLoads key to their plist.

macOS autoUpdater download behavior with network resumption

The update ZIP is streamed to disk rather than held in memory. When the server answers with an ETag or Last-Modified header and honors Range requests, a download interrupted by network change, sleep, or app quitting continues from where it stopped on the next update check, including after relaunch; otherwise it starts over.

macOS autoUpdater update entry validation

An update entry may declare sha256 (hex digest) and size (bytes) alongside url; a download that does not match them is discarded before unpacking and error is emitted.

macOS autoUpdater delta patch support

An update entry may carry delta, an object with from_version, url, sha256 and size, offering a binary patch from one earlier build. When from_version equals the running app's CFBundleVersion, that patch is downloaded instead of the ZIP, applied to a copy of the running app, and verified with code signing; on any failure the ZIP is downloaded. Patches are made with Sparkle's BinaryDelta create from exact bundles that shipped.

Windows autoUpdater MSIX and Squirrel.Windows support

On Windows, the autoUpdater module automatically selects the appropriate update mechanism based on packaging. For MSIX packages (detected via process.windowsStore), it uses the MSIX updater supporting direct MSIX file links and JSON update feeds. For apps installed via traditional installers, it uses Squirrel.Windows. Electron automatically detects the packaging format and uses the appropriate updater without manual configuration.

Squirrel.Windows first run behavior

Squirrel.Windows apps will launch with the --squirrel-firstrun argument immediately after installation. During this time, Squirrel.Windows will obtain a file lock on the app, and autoUpdater requests will fail until the lock is released. In practice, autoUpdater cannot check for updates on first launch for the first few seconds. This can be worked around by not checking for updates when process.argv contains the --squirrel-firstrun flag or by setting a 10-second timeout on update checks.

Squirrel.Windows Application User Model ID requirement

The installer generated with Squirrel.Windows creates a shortcut icon with an Application User Model ID in the format com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE (examples: com.squirrel.slack.Slack, com.squirrel.code.Code). You must use the same ID for your app with app.setAppUserModelId API, otherwise Windows will not be able to pin your app properly in task bar.

MSIX packages autoUpdater additional functionality

When an app is packaged as MSIX, the autoUpdater module provides additional functionality: use the allowAnyVersion option in setFeedURL() to allow updates to older versions (downgrades), and support for direct MSIX file links or JSON update feeds similar to Squirrel.Mac format.

autoUpdater events: error, checking-for-update, update-available, update-not-available

The autoUpdater object emits these events: error (returns Error), checking-for-update (emitted when checking for update starts), update-available (emitted when update is available and downloaded automatically), update-not-available (emitted when no update is available).

autoUpdater event: update-downloaded

The update-downloaded event is emitted when an update has been downloaded. It returns event (Event), releaseNotes (string), releaseName (string), releaseDate (Date), and updateURL (string). With Squirrel.Windows only releaseName is available. It is not strictly necessary to handle this event; a successfully downloaded update will still be applied the next time the application starts.

autoUpdater event: before-quit-for-update

The before-quit-for-update event is emitted after a user calls quitAndInstall(). When this API is called, the before-quit event is not emitted before all windows are closed. You should listen to this event if you wish to perform actions before the windows are closed while a process is quitting, as well as listening to before-quit.

autoUpdater.setFeedURL() method

Sets the URL and initializes the auto updater. Parameters: options (Object) with properties: url (string, required) - the update server URL (for Windows MSIX this can be either a direct link to MSIX file or JSON endpoint), headers (Record<string, string>, optional, macOS only) - HTTP request headers, serverType (string, optional, macOS only) - can be 'json' or 'default', allowAnyVersion (boolean, optional, Windows only) - if true allows downgrades to older versions for MSIX packages, defaults to false.

autoUpdater.getFeedURL() method

Returns a string representing the current update feed URL.

autoUpdater.checkForUpdates() method

Asks the server whether there is an update. You must call setFeedURL before using this API. If an update is available it will be downloaded automatically. Calling autoUpdater.checkForUpdates() twice will download the update two times.

autoUpdater.quitAndInstall() method

Restarts the app and installs the update after it has been downloaded. It should only be called after update-downloaded has been emitted. Under the hood, calling autoUpdater.quitAndInstall() will close all application windows first, and automatically call app.quit() after all windows have been closed. It is not strictly necessary to call this function to apply an update, as a successfully downloaded update will always be applied the next time the application starts.

Give your agent this brain