Complete solution to build ready for distribution and "auto update" installers of your app for OS X, Windows and Linux.
- Native application dependencies compilation (only if two-package.json project layout used).
- Auto Update ready application packaging.
- Code Signing on a CI server or development machine.
- Build version management.
- Publishing artifacts to GitHub Releases.
Real project example — onshape-desktop-shell.
- Ensure that required fields are specified in the application
build field must be specified:
This object will be used as a source of electron-packager options. You can specify any other options here.
buildin the root of the project and put your
background.png(OS X DMG background),
icon.icns(OS X app icon) and
icon.ico(Windows app icon). Linux icon set will be generated automatically on the fly from the OS X
Add scripts to the development
And then you can run
npm run packor
npm run dist(to package in a distributable format (e.g. DMG, windows installer, NuGet package)).
Install required system packages.
Please note — local icon file url is not accepted, must be https/http.
- If you don't plan to build windows installer, you can omit it.
- If your project repository is public on GitHub, it will be
Distributable Format Configuration
In the development
build field can be specified to customize distributable format:
As you can see, you need to customize OS X options only if you want to provide custom
Don't customize paths to background and icon, — just follow conventions (if you don't want to use
build as directory of resources — please create issue to ask ability to customize it).
electron-builder produces all required artifacts:
.dmg: OS X installer, required for OS X user to initial install.
-mac.zip: required for Squirrel.Mac.
-x64.exe: Windows installer, required for Windows user to initial install. Please note — your app must handle Squirrel.Windows events. See real example.
.full-nupkg: required for Squirrel.Windows.
-i386.deb: Linux Debian package. Please note — by default the most effective xz compression format used.
You need to deploy somewhere releases/downloads server.
In general, there is a possibility to setup it as a service for all (it is boring to setup own if cloud service is possible). May be it will be soon (feel free to file an issue to track progress). It is safe since you should sign your app in any case (so, even if server will be compromised, users will not be affected because OS X will just block unsigned/unidentified app).
OS X and Windows code singing is supported.
On a development machine set environment variable
CSC_NAME to your identity (recommended). Or pass
export CSC_NAME="Developer ID Application: Your Name (code)"
Travis, AppVeyor and other CI servers
To sign app on build server:
- Export certificate. Strong password must be used. Consider to not use special characters (for bash) because “values are not escaped when your builds are executed”.
*.p12file (e.g. on Google Drive).
- Set (Travis or AppVeyor)
travis encrypt "CSC_LINK='https://drive.google.com/uc?export=download&id=***'" --add travis encrypt 'CSC_KEY_PASSWORD=beAwareAboutBashEscaping!!!' --add
Build Version Management
CFBundleVersion (OS X) and
FileVersion (Windows) will be set automatically to
build_number on CI server (Travis, AppVeyor and CircleCI supported).
node_modules/.bin/build --help to get actual CLI usage guide.
In most cases you should not explicitly pass flags, so, we don't want to promote it here (npm lifecycle is supported and script name is taken in account).
Want more — please file issue.
node_modules/electron-builder/out/electron-builder.d.ts. Typings is supported.
Old API (< 2.8)
Old API is deprecated, but not dropped. You can use it as before. Please note — new API by default produces Squirrel.Windows installer, set
target to build NSIS: