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.
portable(portable app without installation), AppX (Windows Store), Squirrel.Windows.
|“I want to configure electron-builder”||See options|
|“I have a question”||Open an issue or join the chat|
|“I found a bug”||Open an issue|
|“I want to donate”||Donate with Donorbox or Paypal|
Real project example — onshape-desktop-shell.
yarn add electron-builder --dev
7zip-bin-* packages are
optionalDependencies, which may require manual install if you have npm configured to not install optional deps by default.
Specify the build configuration in the
package.json as follows:
See all options.
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).
Add the scripts key to the development
Then you can run
yarn dist (to package in a distributable format (e.g. dmg, windows installer, deb package)) or
yarn 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 script
"postinstall": "electron-builder install-app-deps" to your
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
💡 Don't use npm (neither
.npmrc) for configuring electron headers. Use node-gyp-rebuild bin instead.
Install the required system packages if you are not on macOS 10.12+.
Please note that everything is packaged into an asar archive by default.
For an app that will be shipped to production, you should sign your application. See Where to buy code signing certificates.
node_modules/.bin/electron-builder --help (
node_modules/.bin/electron-builder build --help for `build subcommand) 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 Deprecated. Use -c.extraMetadata. --prepackaged, --pd The path to prepackaged app (to pack in a distributable format) --projectDir, --project The path to project directory. Defaults to current working directory. --config, -c The path to an electron-builder config. Defaults to `electron-builder.yml` (or `json`, or `json5`), see https://goo.gl/YFRJOM Publishing: --publish, -p Publish artifacts (to GitHub Releases), see https://goo.gl/WMlr4n [choices: "onTag", "onTagOrDraft", "always", "never", undefined] --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", undefined] --arch The target arch (preferred to use --x64 or --ia32) [choices: "ia32", "x64", "all", undefined] Other: --help Show help [boolean] --version Examples: electron-builder -mwl build for macOS, Windows and Linux electron-builder --linux deb tar.xz build deb and tar.xz for Linux electron-builder --win --ia32 build for Windows ia32 electron-builder --em.foo=bar set package.json property `foo` to `bar` electron-builder configure unicode options for NSIS --config.nsis.unicode=false
node_modules/electron-builder/out/electron-builder.d.ts. Typings is supported.
"use strict"const builder =const Platform = builderPlatform// Promise is returnedbuilder
You can use electron-builder only to pack your electron app in a AppImage, Snaps, Debian package, NSIS, macOS installer component package (
and other distributable formats.
./node_modules/.bin/build --prepackaged <packed dir>
--projectDir (the path to project directory) option also can be useful.
See the Wiki for more documentation.
Set the DEBUG environment variable to debug what electron-builder is doing: