Electron Docs
See publish configuration for information on how to configure your local or CI environment for automated deployments.
Simplified auto-update is supported on Windows if you use the default NSIS target, but is not supported for Squirrel.Windows.
Differences between electron-updater and built-in autoUpdater
- It doesn't require a dedicated release server.
- Code signature validation not only on macOS, but also on Windows.
- electron-builder produces and publishes all required metadata files and artifacts.
- Download progress supported on all platforms.
- Staged rollouts supported on all platforms.
- Actually, built-in autoUpdater is used inside on macOS.
- Different providers supported out of the box (GitHub Releases, Amazon S3, DigitalOcean Spaces, Bintray and generic HTTP(s) server).
- You need only 2 lines of code to make it work.
Quick Setup Guide
Install electron-updater as an app dependency.
Use
autoUpdater
fromelectron-updater
instead ofelectron
:`
js import { autoUpdater } from "electron-updater"`
Or if you don't use ES6:
const autoUpdater = require("electron-updater").autoUpdater
Call
autoUpdater.checkForUpdatesAndNotify()
. Or, if you need custom behaviour, implementelectron-updater
events, check examples below.
NOTICE:
- Do not call setFeedURL. electron-builder automatically creates
app-update.yml
file for you on build in theresources
(this file is internal, you don't need to be aware of it). zip
target for macOS is required for Squirrel.Mac, whereaslatest-mac.yml
cannot be created, which causesautoUpdater
error. Default target for macOSdmg
+zip
, you don't need to explicitly specify target.
Examples
- Example in Typescript using system notifications.
- A complete example showing how to use.
- An encapsulated manual update via menu.
Debugging
You don't need to listen all events to understand what's wrong. Just set logger
. electron-log is recommended (it is an additional dependency that you can install if needed).
autoUpdater.logger = require("electron-log")
autoUpdater.logger.transports.file.level = "info"
Staged Rollouts
Staged rollouts allow you to distribute the latest version of your app to a subset of users that you can increase over time, similar to rollouts on platforms like Google Play.
Staged rollouts are controlled by manually editing your latest.yml
/ latest-mac.yml
(channel update info file).
version: 1.1.0
path: TestApp Setup 1.1.0.exe
sha512: Dj51I0q8aPQ3ioaz9LMqGYujAYRbDNblAQbodDRXAMxmY6hsHqEl3F6SvhfJj5oPhcqdX1ldsgEvfMNXGUXBIw==
stagingPercentage: 10
Update will be shipped to 10% of userbase.
If you want to pull a staged release because it hasn't gone well, you must increment the version number higher than your broken release. Because some of your users will be on the broken 1.0.1, releasing a new 1.0.1 would result in them staying on a broken version.
File Generated and Uploaded in Addition
latest.yml
(or latest-mac.yml
for macOS, or latest-linux.yml
for Linux) will be generated and uploaded for all providers except bintray
(because not required, bintray
doesn't use latest.yml
).
Private GitHub Update Repo
You can use a private repository for updates with electron-updater by setting the GH_TOKEN
environment variable (on user machine) and private
option. If GH_TOKEN
is set, electron-updater will use the GitHub API for updates allowing private repositories to work.
Only for very special cases — not intended and not suitable for all users.
Note: The GitHub API currently has a rate limit of 5000 requests per user per hour. An update check uses up to 3 requests per check.
Events
The autoUpdater
object emits the following events:
Event: error
error
Error
Emitted when there is an error while updating.
Event: checking-for-update
Emitted when checking if an update has started.
Event: update-available
info
UpdateInfo (for generic and github providers) | VersionInfo (for Bintray provider)
Emitted when there is an available update. The update is downloaded automatically if autoDownload
is true
.
Event: update-not-available
Emitted when there is no available update.
info
UpdateInfo (for generic and github providers) | VersionInfo (for Bintray provider)
Event: download-progress
progress
ProgressInfobytesPerSecond
percent
total
transferred
Emitted on progress. Only supported over Windows build, since Squirrel.Mac
does not provide this data.
Event: update-downloaded
info
UpdateInfo — for generic and github providers. VersionInfo for Bintray provider.
API
- electron-updater
- .AppUpdater ⇐
EventEmitter
.checkForUpdates()
⇒Promise<UpdateCheckResult>
.checkForUpdatesAndNotify()
⇒Promise< | UpdateCheckResult>
.downloadUpdate(cancellationToken)
⇒Promise<any>
.getFeedURL()
⇒undefined
|null
|String
.setFeedURL(options)
.quitAndInstall(isSilent, isForceRunAfter)
.FileInfo
.Logger
.UpdateInfo
⇐VersionInfo
.UpdateCheckResult
- .UpdaterSignal
.VersionInfo
- .AppUpdater ⇐
AppUpdater ⇐ EventEmitter
Kind: class of electron-updater
<br/> Extends: EventEmitter
Properties
autoDownload
=true
Boolean - Whether to automatically download an update when it is found.allowPrerelease
=false
Boolean - GitHub provider only. Whether to allow update to pre-release versions. Defaults totrue
if application version contains prerelease components (e.g.0.12.1-alpha.1
, herealpha
is a prerelease component), otherwisefalse
.If
true
, downgrade will be allowed (allowDowngrade
will be set totrue
).fullChangelog
=false
Boolean - GitHub provider only. Get all release notes (from current version to latest), not just the latest.allowDowngrade
=false
Boolean - Whether to allow version downgrade (when a user from the beta channel wants to go back to the stable channel).currentVersion
String - The current application version.requestHeaders
[key: string]: string - The request headers.logger
Logger - The logger. You can pass electron-log, winston or another logger with the following interface:{ info(), warn(), error() }
. Set it tonull
if you would like to disable a logging feature.signals
=new UpdaterSignal(this)
UpdaterSignal - For type safety you can use signals, e.g.autoUpdater.signals.updateDownloaded(() => {})
instead ofautoUpdater.on('update-available', () => {})
configOnDisk
=new Lazy<any>(() => this.loadUpdateConfig())
Lazy<any>
Methods
- .AppUpdater ⇐
EventEmitter
.checkForUpdates()
⇒Promise<UpdateCheckResult>
.checkForUpdatesAndNotify()
⇒Promise< | UpdateCheckResult>
.downloadUpdate(cancellationToken)
⇒Promise<any>
.getFeedURL()
⇒undefined
|null
|String
.setFeedURL(options)
.quitAndInstall(isSilent, isForceRunAfter)
appUpdater.checkForUpdates()
⇒ Promise<UpdateCheckResult>
Asks the server whether there is an update.
appUpdater.checkForUpdatesAndNotify()
⇒ Promise< | UpdateCheckResult>
appUpdater.downloadUpdate(cancellationToken)
⇒ Promise<any>
Start downloading update manually. You can use this method if autoDownload
option is set to false
.
Returns: Promise<any>
- Path to downloaded file.
- cancellationToken
CancellationToken
appUpdater.getFeedURL()
⇒ undefined
| null
| String
appUpdater.setFeedURL(options)
Configure update provider. If value is string
, GenericServerOptions will be set with value as url
.
- options
PublishConfiguration
|String
|GithubOptions
|S3Options
|SpacesOptions
|GenericServerOptions
|BintrayOptions
- If you want to override configuration in theapp-update.yml
.
appUpdater.quitAndInstall(isSilent, isForceRunAfter)
Restarts the app and installs the update after it has been downloaded. It should only be called after update-downloaded
has been emitted.
Note:autoUpdater.quitAndInstall()
will close all application windows first and only emit before-quit
event on app
after that. This is different from the normal quit event sequence.
- isSilent
Boolean
- windows-only Runs the installer in silent mode. - isForceRunAfter
Boolean
- windows-only Run the app after finish even on silent install.
FileInfo
Kind: interface of electron-updater
<br/> Properties
name
Stringurl
StringpackageInfo
module:builder-util-runtime.PackageFileInfosha2
Stringsha512
Stringheaders
[key: string]: string
Logger
Kind: interface of electron-updater
<br/>
logger.debug(message)
- message
String
logger.error(message)
- message
any
logger.info(message)
- message
any
logger.warn(message)
- message
any
UpdateInfo
⇐ VersionInfo
Kind: interface of electron-updater
<br/> Extends: VersionInfo
Properties
path
Stringsha512
StringgithubArtifactName
StringreleaseName
String - The release name.releaseNotes
String | Array<module:builder-util-runtime.ReleaseNoteInfo> - The release notes. List ifupdater.fullChangelog
is set totrue
,string
otherwise.releaseDate
String - The release date.stagingPercentage
Number - The staged rollout percentage, 0-100.version
String - The version.
UpdateCheckResult
Kind: interface of electron-updater
<br/> Properties
versionInfo
module:builder-util-runtime.VersionInfofileInfo
FileInfodownloadPromise
Promise<Array<String>>cancellationToken
CancellationToken
UpdaterSignal
Kind: class of electron-updater
<br/>
updaterSignal.login(handler)
Emitted when an authenticating proxy is asking for user credentials.
- handler
module:electron-updater.__type
updaterSignal.progress(handler)
- handler
callback
updaterSignal.updateCancelled(handler)
- handler
callback
updaterSignal.updateDownloaded(handler)
- handler
callback
VersionInfo
Kind: interface of electron-updater
<br/> Properties
version
String - The version.
相关npm包集合
- electron-packager
- electron-builder
- electron-updater
- electron-download
- electron-apps
- electron-to-chromium
- awesome-electron
- electron-debug
- electron-rebuild