electron-builder

Complete solution to package and build ready for distribution and "auto update" Electron app for MacOS, Windows and Linux.

• NPM packages management:
  • Native application dependencies compilation (only if two-package.json project structure used).
  • Development dependencies are never included. You don't need to ignore it explicitly.
• Code Signing on a CI server or development machine.
• Auto Update ready application packaging.
• Build version management.
• Numerous target formats:
  • All platforms: 7z, zip, tar.xz, tar.lz, tar.gz, tar.bz2.
  • MacOS: dmg, mas.
  • Linux: AppImage, deb, rpm, freebsd, pacman, p5p, apk.
  • Windows: NSIS, Squirrel.Windows.
• Publishing artifacts to GitHub Releases.

appdmg are used under the hood.

Note: appdmg (and the platform specific 7zip-bin-* packages) are optionalDependencies, which may require manual install if you have npm configured to not install optional deps by default.

Real project example — onshape-desktop-shell.

Two package.json structure

We 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?

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 (see #39).
2. No need to specify which files to include in the app (because development files reside outside the app directory).

Please see Loading App Dependencies Manually and #379.

Configuration

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

For a production app you need to sign your application, see Where to buy code signing certificate.

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": {
     "appId": "your.id",
     "category": "your.app.category.type",
     "win": {
       "iconUrl": "(windows-only) https link to icon"
     }
   }

   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 (MacOS DMG background), icon.icns (MacOS app icon) and icon.ico (Windows app icon).

   Linux icon set will be generated automatically on the fly from the MacOS 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": {
     "pack": "build --dir",
     "dist": "build"
   }

   And then you can run npm run dist (to package in a distributable format (e.g. dmg, windows installer, deb package)) or npm run pack (useful to test).

   Add script "postinstall": "install-app-deps" if two package.json structure is used to automatically install application dependencies.

5. Install required system packages.

Please note — packaged into an asar archive by default.

Auto Update

electron-builder produces all required artifacts:

• .dmg: MacOS installer, required for MacOS 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.

For auto updating to work, you must implement and configure Electron's autoUpdater module (example). You also need to deploy your releases to a server. Consider using Nuts (GitHub as a backend to store assets), Electron Release Server or Squirrel Updates Server. See the Publishing Artifacts section of the Wiki for information on configuring your CI environment for automatic deployment.

For windows consider only distributing 64-bit versions.

CLI Usage

Execute node_modules/.bin/build --help to get actual CLI usage guide.

Building:
  --mac, -m, -o, --osx, --macos  Build for MacOS, accepts target list (see
                                 https://goo.gl/HAnnq8).                 [array]
  --linux, -l                    Build for Linux, accepts target list (see
                                 https://goo.gl/O80IL2)                  [array]
  --win, -w, --windows           Build for Windows, accepts target list (see
                                 https://goo.gl/dL4i8i)                  [array]
  --x64                          Build for x64                         [boolean]
  --ia32                         Build for ia32                        [boolean]
  --dir                          Build unpacked dir. Useful to test.   [boolean]
  --extraMetadata, --em          Inject properties to application package.json

Publishing:
  --publish, -p  Publish artifacts (to GitHub Releases), see
                 https://goo.gl/WMlr4n
                           [choices: "onTag", "onTagOrDraft", "always", "never"]
  --draft        Create a draft (unpublished) release                  [boolean]
  --prerelease   Identify the release as a prerelease                  [boolean]

Deprecated:
  --platform  The target platform (preferred to use --mac, --win or --linux)
               [choices: "mac", "osx", "win", "linux", "darwin", "win32", "all"]
  --arch      The target arch (preferred to use --x64 or --ia32)
                                                 [choices: "ia32", "x64", "all"]

Other:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

Examples:
  build -mwl                build for MacOS, Windows and Linux
  build --linux deb tar.xz  build deb and tar.xz for Linux
  build --win --ia32        build for Windows ia32
  build --em.foo=bar        set application package.json property `foo` to `bar`

Programmatic Usage

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

"use strict"

const builder = require("electron-builder")
const Platform = builder.Platform

// Promise is returned
builder.build({
  targets: Platform.MAC.createTarget(),
  devMetadata: {
    "//": "build and other properties, see https://goo.gl/5jVxoO"
  }
})
  .then(() => {
    // handle result
  })
  .catch((error) => {
    // handle error
  })

Donations

Donate with PayPal.

Further Reading

See the Wiki for more documentation.