Auto-updating apps for Windows and OSX using Electron: The complete guide (2023)

You’ve made an amazing desktop app using Electron in no time, and you’ve just shipped it to your users. While you’re chilling like a villain, you may realise that you have missed one important bit: how are users going to get the next version of that amazing piece of software that you’ve just created? Yes, of course they can uninstall/install the app, but that’s lame, isn’t it?

A quick glance at Electron’s documentation, and you will notice that the framework ships with an auto-updater module, which is simply an interface to another framework — Squirrel. Squirrel will check for new versions in the background (or when you tell it to), download the new version, and handle the upgrade for you automagically when you start or restart the app.

Sadly things are not as easy as they look on paper — there are differences in how auto-updating works on OSX and Windows (there is no support for Linux as of now) and documentation is scattered across multiple repositories. I’ve spent a fair amount of time trying to make everything work, so I decided it’s worth putting what I’ve learnt into a little guide, that should (hopefully) save some of your time.

Although everything described should work on both Windows and OSX, for the sake of clarity—I am running everything on Mac OSX 10.11, with the exception of building the installer for Windows.

Suggestions to improve or update this guide? Drop me a tweet!

Before we look at implementing auto-updating, there’s one important step — packaging. I assume that the majority of people have this working, using electron-packager, but there are a couple of things which are easy to miss.

Notice the extra package.json fields — productName, author and description — which are not necessary for packaging, but will be picked up by the Squirrel Installer for Windows.

Code-signing the application is not required for auto-updating, but is highly desirable. For OSX, you’ll need an Apple Developer Certificate, and then you just replace this parameter for the pack:osx script:

(Video) Electron app for MacOS | Auto update demo using electron builder (with proper code signing)

--sign='Developer ID Application: My Company Ltd (ABCDEFGH10)'

with whatever you have in Keychain Access > My Certificates in OSX.

I haven’t got code-signing working for Windows yet, but you can have a look at this excellent tutorial on the topic.

Specifically for Windows, it’s good to pass all the optional version-string parameters to electron-packager, such as company name and product name and so on. Once we generate the Squirrel installer for Windows, the app will show up with the right metadata in Windows’ start menu, instead of Atom’s default data.

So, let’s get started!

Auto-updating for OSX is handled by Squirrel.Mac, which is built-in Electron. Which means that you just have to package your app, and you’re good to go!

Well, not quite.

The way Squirrel.Mac works is by checking a given API endpoint to see if there is a new version of the app. If there is no new version, the endpoint should return HTTP 204. If there is a new version, however, it will expect a HTTP 200 JSON-formatted response, containing a url to a .zip file:

{
"url": "http://mysite.com/path/to/zip/MyApp.zip"
}

Squirrel will make an application/zip request using that url, download the file, and fire up the final event to let you know that the update is ready to install. Everything is handled automatically for you.

If you’re not quite sure how the server should like, here’s a super-minimal Node.js/Express app, which assumes the following directory structure:

(Video) BPJS: Electron app - Part 10 - Auto-updating Electron.js app

└── releases
├── darwin
│ ├── 1.0.0
│ ├── 1.0.2
│ └── 1.0.3
└── win32

It will serve files from the local filesystem, which is not ideal — I suggest getting those files on Amazon S3 instead.

You can call the endpoint from Electron in development like so:

http://localhost:3000/updates/latest?v=1.0.1

Where ?v=1.0.1 is your current app version.

Now that you have the server and endpoint in place, handling updating in the app is quite simple.

In your main Electron application file, require the auto-updater module, grab the current OS and your app version:

const autoUpdater = require('auto-updater');
const appVersion = require('./package.json').version;
const os = require('os').platform();

And configure the endpoint, which is going to be different for Windows and OSX (you’ll see why when we get to the Windows part):

There are a number of events fired by the autoUpdater module, which you can implement and send to the renderer process: check auto-updater documentation page for more info. Depending on how you decide to handle the event and notify the user, all you need to do in the end is

autoUpdater.quitAndInstall();

in the main application file, and the app will restart with the new version in place. Boom!

As you would expect, auto-updating on Windows is done via Squirrel.Windows. The process, however, is completely different to the one for OSX.

(Video) Electron autoupdater part 1

Unlike Squirrel.Mac, Squirrel.Windows does not require an API endpoint to check for new versions — all it needs is a file server, so you can simply drop your files in an Amazon S3 bucket. The Squirrel Updater, however, is not bundled in Electron, and is a 3rd party dependency. This means that you’ll need to generate an installer for your packaged Windows app, that will include the Squirrel Updater as well.

The good news is that the installer and updater for Windows is quite slick—it installs and launches the app on-the-fly, when you launch the Setup.exe. No boring installer wizards and clicking Next, Next, Next, Finish, like most installers for Windows. It also generates delta packages, so you don’t have to download the whole app when you do an update, which is ace.

The bad news (for Mac users, at least) is that I couldn’t build the installer properly on OSX, so I suggest you download a Windows VM for VirtualBox, and install Node.js on it.

Assuming that you’ve configured and set the correct update feed, using the code for OSX above, the only thing left code-wise is to handle a few Squirrel.Windows events, which are different than the ones for OSX. You can see an example here. There is an easier way, however — just install the electron-squirrel-startup npm module:

npm install electron-squirrel-startup --save-dev

And place that line at the top of your main Electron application file:

if (require('electron-squirrel-startup')) return;

Squirrel.Windows events should be handled as early as possible, apparently, so that’s the way to go.

Finally, to generate the installer, we’re going to use Atom’s grunt-electron-installer. Why this is a grunt plugin, instead of a simple command-line utility — I don’t know, but that’s how it is.

Update: Turns out the Electron team are working on a stand-alone installer package called electron-winstaller, which has the same API as the grunt task.

Zip the win32 folder, produced by electron-packager, and copy it over to the Virtual Machine. Outside that folder, you’ll need to configure the grunt task that will build the installer, so you should install all dependencies first:

(Video) Auto Update Electron application Free | Part 1

npm install -g grunt-cli
npm install grunt grunt-electron-installer --save-dev

Assuming that the Windows compiled package is in a folder called MyApp-win32-ia32, here’s how the Gruntfile could look like:

Note that if you want to code-sign your files and the installer, you should supply all params to the task config, too.

Running the grunt task should produce a bunch of files in the ./dist folder:

grunt create-windows-installer

You expect to see something similar to

└── dist
├── MyApp.1.0.0.nupkg
├── MyApp-1.0.0-full.nupkg
├── RELEASES
├── Setup.exe

With the next release, the installer will generate a delta packages automatically, too.

Now the easiest part — grab all those files, and dump them in an S3 bucket. The url pointing to that folder, containing the RELEASES and nupkg files should be the updateFeed url given to the autoUpdater, when running on Windows (we’ve done that earlier for OSX, so go back to the main application file and update it).

Note: there is currently an issue with the installer related to node-rcedit — it throws an error when it tries to modify the .exe file to place some of the metadata and replace the default icon. You can see the issue here. Unfortunately if you want to change the icon or put the real data onto the installer file, you’ll have to do it manually with ResHacker.

Hope this helps and serves as a good starting point to anyone who’s working on auto-updating with Electron. If you spot anything that I’ve missed, or have any suggestions for improvement (there’s definitely room for that) — feel free to drop me a tweet to let me know! Also, keep in mind that Electron is a fast-evolving framework, so always make sure you’re reading the right documentation for your version, since Electron APIs changes quite often.

(Video) ⚡talks - Packaging Electron Apps for Windows + Adding in Auto Update Functionality

I’m Svilen — a full-stack web developer and co-founder at Heresy. We’re always looking for engineers who enjoy working with the latest technologies and solving challenging problems. If you’re curious, check out jobs page!

FAQs

How do I update my electron JS app? ›

Using update.electronjs.org

The Electron maintainers provide a free auto-updating service for open-source apps at https://update.electronjs.org. Its requirements are: Your app runs on macOS or Windows. Your app has a public GitHub repository.

How do I update my Electron Forge? ›

Open Source Apps - update.electronjs.org

Open Source apps hosted on github.com can use a free auto update service from the Electron team, update.electronjs.org . To use this with Forge, set up the GitHub publisher and add the update-electron-app module to your app.

How do you deploy an Electron app? ›

With prebuilt binaries​

The location of Electron's prebuilt binaries is indicated with electron/ in the examples below. Then execute Electron. app on macOS, electron on Linux, or electron.exe on Windows, and Electron will start as your app. The electron directory will then be your distribution to deliver to users.

What is Electron Forge? ›

Electron Forge is a complete tool for creating, publishing, and installing modern Electron applications.

What is Electron notarize? ›

A notarized app is a macOS app that was uploaded to Apple for processing before it was distributed. When you export a notarized app from Xcode, it code signs the app with a Developer ID certificate and staples a ticket from Apple to the app. The ticket confirms that you previously uploaded the app to Apple.

Videos

1. Distributing Electron Applications : Setup Auto Updates for macOS | packtpub.com
(Packt Video)
2. Autoupdater Electron App Free | Part 4 Final
(i learned today)
3. Build a Desktop App with Electron... But Should You?
(Fireship)
4. Electron Build Desktop Apps HTML\CSS\JS | Package, Build and Deploy your App 05
(CoderOne)
5. BPJS: Electron app - Livestream 13 - Setting up Electron auto-update
(Tim Ermilov)
6. Build an Electron App in Under 60 Minutes
(Traversy Media)
Top Articles
Latest Posts
Article information

Author: Msgr. Refugio Daniel

Last Updated: 04/01/2023

Views: 6012

Rating: 4.3 / 5 (74 voted)

Reviews: 81% of readers found this page helpful

Author information

Name: Msgr. Refugio Daniel

Birthday: 1999-09-15

Address: 8416 Beatty Center, Derekfort, VA 72092-0500

Phone: +6838967160603

Job: Mining Executive

Hobby: Woodworking, Knitting, Fishing, Coffee roasting, Kayaking, Horseback riding, Kite flying

Introduction: My name is Msgr. Refugio Daniel, I am a fine, precious, encouraging, calm, glamorous, vivacious, friendly person who loves writing and wants to share my knowledge and understanding with you.