Electron Builder — Package Electron Apps for Every Platform

Introduction

Electron Builder is the standard packaging and distribution tool for Electron applications. It handles code signing, notarization, auto-update, and installer creation for macOS, Windows, and Linux from a single declarative configuration in package.json or electron-builder.yml.

What Electron Builder Does

• Creates native installers: DMG and PKG for macOS, NSIS and MSI for Windows, AppImage, deb, rpm, and snap for Linux
• Signs and notarizes macOS builds with Apple Developer credentials
• Signs Windows executables with EV or standard code-signing certificates
• Generates auto-update metadata for seamless in-app updates via electron-updater
• Publishes artifacts to GitHub Releases, S3, or custom update servers

Architecture Overview

Electron Builder reads a declarative config that specifies per-platform targets, then orchestrates a build pipeline: it copies the app source, installs production dependencies, compiles native modules for the target arch, applies code signing, and finally invokes platform-specific packaging tools (NSIS, appdmg, rpmbuild) to produce distributable installers.

Self-Hosting and Configuration

• Add an electron-builder.yml or a build key in package.json to configure targets
• Set CSC_LINK and CSC_KEY_PASSWORD environment variables for code signing
• Use publish configuration to target GitHub Releases, S3, or a generic server
• Multi-arch builds (x64 and arm64) are supported via the --arch flag
• CI integration works out of the box with GitHub Actions, GitLab CI, and CircleCI

Key Features

• Single config file drives all platforms and architectures
• Differential updates reduce download sizes for returning users
• Native module rebuilding for the target Electron version is automatic
• ASAR packing with optional per-file unpack rules for performance
• Monorepo-friendly with workspace and custom directory support

Comparison with Similar Tools

• Electron Forge — offers a more opinionated plugin-based workflow; Electron Builder gives finer control over installer output
• electron-packager — lower-level tool that only bundles the app without creating installers or handling signing
• Tauri — Rust-based alternative to Electron itself, not a packaging tool for existing Electron apps
• pkg — packages Node.js apps into executables but does not target the Electron runtime

FAQ

Q: Can I build for macOS from a Linux CI runner? A: DMG and PKG targets require macOS. You can build non-signed zip targets on Linux but notarization needs a Mac.

Q: How does auto-update work? A: Electron Builder generates update metadata files. The companion library electron-updater checks these files at runtime and applies delta or full updates.

Q: Is ASAR packing required? A: No, but it is enabled by default. It bundles app files into a single archive for faster reads and to prevent casual source inspection.

Q: Does it support Apple Silicon natively? A: Yes. Pass --arm64 or --universal to produce native Apple Silicon or universal binaries.

Sources

• https://github.com/electron-userland/electron-builder
• https://www.electron.build/