A complete solution to package and build a ready for distribution Electron app with “auto update” support out of the box
TypeScript NSIS Shell JavaScript Other
Permalink
Failed to load latest commit information.
.github chore: add issue template Jun 26, 2016
.idea WIP: Electron Auto Updater MacOS support Jan 11, 2017
docker fix(docker): add missing libcurl3 for osslsigncode (#1116) Jan 14, 2017
docs fix: generate latest-mac.json for github in the github directory Jan 16, 2017
packages fix(snap): interface 'platform' doesn't exist Jan 16, 2017
test fix: generate latest-mac.json for github in the github directory Jan 16, 2017
typings fix: generate latest-mac.json for github in the github directory Jan 16, 2017
.babelrc feat: force application signing Dec 12, 2016
.editorconfig feat: support finding electron version in build.electronVersion or el… May 26, 2016
.gitattributes fix(mac): background image isn't displayed in macOS sierra Oct 5, 2016
.gitignore WIP: Electron Auto Updater MacOS support #1089 Jan 10, 2017
.mention-bot chore: rc-producer.yml for IDEA, mention bot config, update deps Dec 5, 2016
.travis.yml fix: electron-builder not generating "latest.yml" file Jan 5, 2017
.yarnclean test: install yarn Oct 21, 2016
CHANGELOG.md fix(dmg): Unable to build with custom path Dec 31, 2016
CONTRIBUTING.md feat(nsis): Change installation directory when not using 'oneClick' w… Jan 5, 2017
LICENSE Initial commit May 21, 2015
MAINTAINING.md refactor: change paths to template after "electron-builder according … Dec 31, 2016
README.md feat: Separate build config from package.json Jan 15, 2017
appveyor.yml fix: to preserve compatibility with old electron-auto-updater (< 0.10… Jan 6, 2017
circle.yml feat(snap): ubuntu-app-platform (disabled by default) Dec 25, 2016
lerna.json refactor: extract packagerApi Jan 10, 2017
package.json fix: generate latest-mac.json for github in the github directory Jan 16, 2017
yarn.lock fix: generate latest-mac.json for github in the github directory Jan 16, 2017

README.md

electron-builder npm version donate

A complete solution to package and build a ready for distribution Electron app for macOS, Windows and Linux with “auto update” support out of the box.

Note: 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.

Yarn is recommended instead of npm.

Configuration

See options for a full reference but consider following the simple guide outlined below first.

For an app that will be shipped to production, you should sign your application. See Where to buy code signing certificates.

Quick Setup Guide

  1. Specify the standard fields in the application package.jsonname, description, version and author.

  2. Specify the build configuration in the development package.json as follows:

    "build": {
      "appId": "your.id",
      "mac": {
        "category": "your.app.category.type"
      },
      "win": {
        "iconUrl": "(windows-only) https link to icon"
      }
    }

    See all options.

  3. Create a directory build in the root of the project and save a background.png (macOS DMG background), icon.icns (macOS app icon) and icon.ico (Windows app icon) into it.

    The Linux icon set will be generated automatically based on the macOS icns file (or you can put them into the build/icons directory if you want to specify them yourself. The filename must contain the size (e.g. 32x32.png) of the icon).

  4. Add the scripts key to the development package.json:

    "scripts": {
      "pack": "build --dir",
      "dist": "build"
    }

    Then you can run npm run dist (to package in a distributable format (e.g. dmg, windows installer, deb package)) or npm run pack (only generates the package directory without really packaging it. This is useful for testing purposes).

    To ensure your native dependencies are always matched electron version, simply add "postinstall": "install-app-deps" to your package.json. Do not use Yarn.

  5. If you have native addons of your own that are part of the application (not as a dependency), add "nodeGypRebuild": true to the build section of your development package.json.
    💡 Don't use npm (neither .npmrc) for configuring electron headers. Use node-gyp-rebuild bin instead.

  6. Installing the required system packages.

Please note that everything is packaged into an asar archive by default.

Auto Update

electron-builder produces all required artifacts, for example, for macOS:

  • .dmg: macOS installer, required for the initial installation process on macOS.
  • -mac.zip: required for Squirrel.Mac.

See the Auto Update section of the Wiki.

CLI Usage

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

Building:
  --mac, -m, -o, --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]
  --armv7l                Build for armv7l                             [boolean]
  --dir                   Build unpacked dir. Useful to test.          [boolean]
  --extraMetadata, --em   Inject properties to package.json (asar only)
  --prepackaged, --pd     The path to prepackaged app (to pack in a
                          distributable format)
  --project               The path to project directory. Defaults to current 
                          working directory.

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", "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 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(),
  config: {
   "//": "build options, see https://goo.gl/ZhRfla"
  }
})
  .then(() => {
    // handle result
  })
  .catch((error) => {
    // handle error
  })

Pack Only in a Distributable Format

You can use electron-builder only to pack your electron app in a AppImage, Snaps, Debian package, NSIS, macOS installer component package (pkg) and other distributable formats.

./node_modules/.bin/build --prepackaged <packed dir>

--project (the path to project directory) option also can be useful.

Donations

Donate with PayPal.

Further Reading

See the Wiki for more documentation.