Neologistic Paraphasic Mumbling

    TypeScript icon, indicating that this package has built-in type declarations

    1.0.7 • Public • Published

    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.

    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 your project with any structure).

    1. For development (./package.json)

      The package.json resides in the root of your project. Here you declare the dependencies for your development environment and build scripts (devDependencies).

    2. For your application (./app/package.json)

      The package.json resides in the app directory. Declare your application dependencies (depencencies) here. Only this directory is distributed with the final, packaged application.


    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 within the application need to be compiled against the electron runtime and all devDependencies need to be compiled against your local node.js environment. Thanks to the two package.json structure, 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.


    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:

        "appId": "",
        "mac": {
          "category": "",
        "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:

        "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).

      If you use the two-package.json project structure, you'll only have your devDependencies in your development package.json and your dependencies in your app package.json. To ensure your dependencies are always updated based on both files, simply add "postinstall": "install-app-deps" to your development package.json. This will basically automatically trigger an npm install within your app directory so you don't have to do this work everytime you install/update your dependencies.

    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:

    • .dmg: macOS installer, required for the initial installation process on macOS.
    • required for Squirrel.Mac.
    • .exe and -ia32.exe: Windows installer, required for the initial installation process on Windows. Please note that your app must handle Squirrel.Windows events. See real world example.
    • .full-nupkg: required for Squirrel.Windows.

    To benefit from auto updates, you have to implement and configure Electron's autoUpdater module (example). You also need to deploy your releases to a server. Consider using Nuts (uses GitHub as a backend to store the assets), Electron Release Server or Squirrel Updates Server. See the Publishing Artifacts section of the Wiki for more information on how to configure your CI environment for automated deployments.

    For Windows consider only distributing 64-bit versions. Or use NSIS.

    CLI Usage

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

      --mac, -m, -o, --osx, --macos  Build for MacOS, accepts target list (see
      --linux, -l                    Build for Linux, accepts target list (see
      --win, -w, --windows           Build for Windows, accepts target list (see
      --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
      --publish, -p  Publish artifacts (to GitHub Releases), see
                               [choices: "onTag", "onTagOrDraft", "always", "never"]
      --draft        Create a draft (unpublished) release                  [boolean]
      --prerelease   Identify the release as a prerelease                  [boolean]
      --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"]
      --help     Show help                                                 [boolean]
      --version  Show version number                                       [boolean]
      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        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{
      targets: Platform.MAC.createTarget(),
      devMetadata: {
        "//": "build and other properties, see"
      .then(() => {
        // handle result
      .catch((error) => {
        // handle error


    Donate with PayPal.

    Further Reading

    See the Wiki for more documentation.


    npm i vrrv-installer-builder

    DownloadsWeekly Downloads






    Last publish


    • avatar