electron-builder

Complete solution to build ready for distribution and "auto update" installers of your app for OS X, Windows and Linux.

npm install electron-builder --save-dev

• Native application dependencies compilation (only if two-package.json project structure used).
• Auto Update ready application packaging.
• Code Signing on a CI server or development machine.
• Build version management.
• Publishing artifacts to GitHub Releases.

electron-packager, appdmg and windows-installer are used under the hood.

Real project example — onshape-desktop-shell.

Two package.json structure

We strongly recommend to use two package.json files (it is not required, you can build project with any structure).

1. For development

   In the root of the project.

Here you declare dependencies for your development environment and build scripts.

2. For your application

   In the app directory. Only this directory is distributed with real application.

Why the two package.json structure is ideal and how it solves a lot of issues (#39, #182, #230)?

1. Native npm modules (those written in C, not JavaScript) need to be compiled, and here we have two different compilation targets for them. Those used in application need to be compiled against electron runtime, and all devDependencies need to be compiled against your locally installed node.js. Thanks to having two files this is trivial.
2. When you package the app for distribution there is no need to add up to size of the app with your devDependencies. Here those are always not included (because reside outside the app directory).

Configuration

See options, but consider to follow simple guide outlined below at first.

In short

1. Specify standard fields in the application package.json — name, description, version and author (for Linux homepage and license are also required).

2. Specify build field in the development package.json:

   "build": {
     "app-bundle-id": "your.id",
     "app-category-type": "your.app.category.type",
     "iconUrl": "(windows only)"
   }

   See options. This object will be used as a source of electron-packager options. You can specify any other options here.

3. Create directory build in 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 icns file (or you can put them into the build/icons directory — filename must contains size (e.g. 32x32.png)).

4. Add scripts to the development package.json:

   "scripts": {
     "postinstall": "install-app-deps",
     "pack": "build",
     "dist": "build"
   }

   And then you can run npm run pack or npm run dist (to package in a distributable format (e.g. dmg, windows installer, deb package)). Both scripts are the same because If script named dist or name has prefix dist:, flag --dist is implied.

5. Install required system packages.

Auto Update

electron-builder produces all required artifacts:

• .dmg: OS X installer, required for OS X user to initial install.
• -mac.zip: required for Squirrel.Mac.
• .exe and -ia32.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.
• -amd64.deb and -i386.deb: Linux Debian package. Please note — by default the most effective xz compression format used.

You need to deploy somewhere releases/downloads server. Consider to use Nuts (GitHub as a backend to store assets) or Electron Release Server.

Code Signing

OS X and Windows code singing is supported. On a development machine set environment variable CSC_NAME to your identity (recommended). Or pass --sign parameter.

export CSC_NAME="Developer ID Application: Your Name (code)"

Travis, AppVeyor and other CI servers

To sign app on build server:

1. 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”.
2. Upload *.p12 file (e.g. on Google Drive).
3. Set (Travis or AppVeyor) CSC_LINK and CSC_KEY_PASSWORD environment variables:

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 version.build_number on CI server (Travis, AppVeyor and CircleCI supported).

CLI Usage

Execute 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.

Programmatic Usage

See node_modules/electron-builder/out/electron-builder.d.ts. Typings is supported.