electron-builder

What is electron-builder?

electron-builder is a complete solution to package and build a ready-for-distribution Electron app with “auto update” support out of the box. It supports numerous target formats and platforms, making it a versatile tool for Electron app developers.

What are electron-builder's main functionalities?

Building for Multiple Platforms

This feature allows you to build your Electron app for multiple platforms such as Windows, macOS, and Linux. The code sample demonstrates how to configure and initiate a build process for a Windows target.

const builder = require('electron-builder');

builder.build({
  targets: builder.Platform.WINDOWS.createTarget(),
  config: {
    appId: 'com.example.app',
    productName: 'ExampleApp',
    directories: {
      output: 'dist'
    }
  }
}).then(() => {
  console.log('Build complete!');
}).catch((error) => {
  console.error('Error during build:', error);
});

Auto Update

The auto-update feature allows your app to automatically check for updates and install them. The code sample shows how to set up the auto-updater to check for updates when the app is ready and handle update events.

const { autoUpdater } = require('electron-updater');

app.on('ready', () => {
  autoUpdater.checkForUpdatesAndNotify();
});

autoUpdater.on('update-available', () => {
  console.log('Update available.');
});

autoUpdater.on('update-downloaded', () => {
  autoUpdater.quitAndInstall();
});

Custom Configuration

This feature allows you to customize the build configuration for your Electron app. The code sample demonstrates how to specify custom directories, files, and target formats for different platforms.

const builder = require('electron-builder');

builder.build({
  config: {
    appId: 'com.example.app',
    productName: 'ExampleApp',
    directories: {
      output: 'dist'
    },
    files: [
      'build/**/*'
    ],
    extraResources: [
      'assets/'
    ],
    win: {
      target: 'nsis'
    },
    mac: {
      target: 'dmg'
    }
  }
}).then(() => {
  console.log('Build complete!');
}).catch((error) => {
  console.error('Error during build:', error);
});

Other packages similar to electron-builder

electron-packager

electron-packager is a command-line tool and Node.js library that bundles Electron-based application source code with a renamed Electron executable and supporting files into folders ready for distribution. Unlike electron-builder, it does not include auto-update support out of the box and is generally considered less feature-rich.

electron-forge

electron-forge is a complete tool for creating, publishing, and installing modern Electron applications. It provides a more integrated development experience compared to electron-builder, including project scaffolding, packaging, and publishing. However, it may not offer the same level of customization and flexibility in build configurations.

electron-updater

electron-updater is a standalone module that provides auto-update functionality for Electron apps. While electron-builder includes auto-update support as part of its feature set, electron-updater can be used independently or in conjunction with other packaging tools like electron-packager.

README

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

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

1. 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 4-step guide outlined below at first.

In short

1. Ensure that required fields are specified in the application package.json:

   Standard name, description, version and author.

   Custom build field must be specified:

   "build": {
     "app-bundle-id": "your.id",
     "app-category-type": "your.app.category.type",
     "iconUrl": "(windows only) A URL to an ICO file to use as the application icon, see details below"
   }
   

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

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

3. 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, NuGet package)).

4. 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 -x64.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.

In general, there is a possibility to setup it as a service for all (it is boring to setup own if cloud service is possible). May be it will be soon (feel free to file an issue to track progress). It is safe since you should sign your app in any case (so, even if server will be compromised, users will not be affected because OS X will just block unsigned/unidentified app).

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.

Old API (< 2.8)

Old API is deprecated, but not dropped. You can use it as before. Please note — new API by default produces Squirrel.Windows installer, set target to build NSIS:

build --target=nsis

Changelog

3.0.0 (2016-03-23)

Bug Fixes

• Linux build fails at icon conversion #239 (c778e2b), closes #239
• Problems downloading electron #180 (0265db9), closes #180
• update winstaller to fix build windows on OS X (c2bd66b)
• zip, dmg and exe filenames do not use productName as intended (bfca0a7)

Code Refactoring

• remove deprecated API (<2.8) (eadd09b)

Features

• copy extra resources to packaged app (cbe3ff8)
• linux icons from custom dir, generate missing from ICNS (7ac4b84)
• remove support of build in the application package.json (46dbfe1), closes #251

BREAKING CHANGES

• build is allowed since 3.0 only in the development package.json
• Deprecated <2.8 API has been removed

<a name="2.9.5"></a>