electron-builder: packaging Electron apps for macOS, Windows and Linux

What electron-builder actually produces

The problem is the last mile of an Electron release. A packaged Chromium app is not a deliverable: macOS users expect a dmg or a pkg, Windows users expect an nsis installer or an MSI, and Linux users expect a deb, an rpm, an AppImage or a snap. Each of those formats has its own metadata, its own signing story and its own update mechanism. electron-builder's claim is that one configuration produces all of them, and that the artifacts it writes are already wired for auto update through the companion electron-updater package.

The audience is teams that already build an Electron app and now have to hand something to users. The README lists the target formats explicitly: 7z, zip, tar.xz, tar.7z, tar.lz, tar.gz, tar.bz2 and a plain dir on every platform, plus dmg, pkg and mas on macOS, AppImage, snap, deb, rpm, freebsd, pacman, p5p and apk on Linux, and nsis, nsis-web, portable, AppX, MSI and Squirrel.Windows on Windows. Publishing targets are GitHub Releases, Amazon S3, DigitalOcean Spaces and Bintray.

One design decision is worth calling out because it shapes the whole tool. Development dependencies are never included in the package, so you do not maintain an ignore list for them. The README also says the two package.json structure is supported but not required, even when you have native production dependencies. If you have read older Electron packaging advice that treats that layout as mandatory, this is a deliberate departure from it.

How the build pipeline handles native modules and tool downloads

electron-builder is a TypeScript monorepo. The repository root holds a pnpm workspace, and the build itself is driven by tsc through tsconfig.build.json, so the packages you consume are compiled from the packages/ directory rather than shipped as loose JavaScript. The npm package name is electron-builder and the updater ships separately as electron-updater, which is why the release feed lists both.

The mechanism that matters most in day-to-day use is native dependency handling. The README states that native application dependencies are compiled, with Yarn support, and that development dependencies are excluded automatically. That compilation step is what makes modules built against a different Node ABI work inside the Electron runtime. There is a dedicated command for it, install-app-deps, which you run when your dependency tree changes without a full rebuild.

The second mechanism is on-demand tooling. The README says electron-builder downloads all required tool files on demand, giving code signing a Windows application and producing an AppX as examples, with no setup required. That is convenient on a developer machine and consequential on CI: the first build on a fresh runner pulls those tools over the network, so a network-restricted build environment needs a cache or a warmed image. The README does not document an offline mode or a full list of what gets fetched.

For parallel work, the README describes building and publishing in parallel and using hard links on a CI server to reduce IO and disk space. That is a real constraint on the machine doing the build: hard links only help when the source and destination live on the same filesystem.

Installing electron-builder and producing a first artifact

The README's quick setup guide starts from electron-quick-start, the official minimal starter, then adds electron-builder as a development dependency. Run these three commands in order and you end up with a working Electron project plus the builder installed.

git clone https://github.com/electron/electron-quick-start
cd electron-quick-start
npm install
npm install electron-builder --save-dev

The install command from the README is written for Yarn, with npm, pnpm and bun named as equivalents.

yarn add electron-builder --dev

If you use Yarn 3, note the PnP caveat. The README says electron-builder still needs a node-modules layout and points at yarnpkg/berry issue 4804, so the .yarnrc.yaml file has to opt out of PnP.

nodeLinker: "node-modules"

After installation, the next step in the guide is to specify the standard configuration for your app. That configuration is the build key in package.json or a separate config file, and the README points at the options page on electron.build for the full key list. The README does not spell out a minimal config block in the section available here, so treat the linked configuration page as the source of truth rather than copying a snippet from a blog post. Once configured, the build command is the CLI entry point, and the README's own table points people who want to configure the tool at the configuration docs and people who hit a bug at the issue tracker.

Version requirements are strict. The README states that Node.js 22.12.0 or newer is required for v27, and that v27 is a major release with breaking changes: native ESM, the Node floor, and removed deprecated APIs. If you are on v26, the README says to read What's New in v27 first because it covers silent default changes, then read the full breaking changes page before upgrading.

The v27 migration command and what it does not fix

The upgrade path is more scripted than most. The README gives an automated migration command that rewrites your configuration in place.

electron-builder migrate-schema

A tool that edits your config file deserves a branch and a diff. The README does not document a dry-run flag for this command, and it does not describe a rollback path, so the safe procedure is to commit your current configuration first and compare what the command writes. The migration guide is a separate document, MIGRATION.md at the repository root, with a web version at electron.build/docs/migration/v26-to-v27.

The reason to be careful is stated plainly in the README: v27 changes silent defaults in addition to removing deprecated APIs. A schema rewrite catches removed keys. It cannot tell you that a default you were relying on without writing it down has moved. That class of change only shows up when you build and inspect the output, which is why the README tells you to read the breaking changes page rather than only running the command.

Where electron-builder is the wrong tool

The most concrete limitation is the Node.js floor. v27 requires Node.js 22.12.0 or newer. If your CI image, your corporate build agents or a downstream toolchain are pinned below that, you either upgrade all of them or you stay on v26. The README presents the v27 line as the current one, so staying behind has a cost, but the requirement is not negotiable within v27.

The second limitation is the tool download behaviour. Because required tool files are fetched on demand, a build environment with no outbound network access will fail at the point where a format needs a tool that is not already cached. The README does not document an offline or air-gapped mode. If your release pipeline runs in a sealed network, that is a design mismatch you need to solve at the image layer, not in the config.

The third is scope. electron-builder is a packager and publisher. It does not scaffold, run or hot-reload your application, and it does not manage your renderer build. The README's own framing is packaging, code signing and auto update. If what you actually need is a plugin system that hooks arbitrary steps of the development lifecycle, this is a narrower tool than that.

Finally, Yarn 3 users inherit a constraint that has nothing to do with electron-builder's own design: PnP has to be turned off in .yarnrc.yaml. The README is explicit about this and links the upstream issue, which means it is a known, accepted incompatibility rather than a bug being fixed.

electron-builder vs Electron Forge and CI-only builders

The comparison people search for is electron-builder versus Electron Forge, and the difference is architectural rather than cosmetic. Forge is organized around a plugin and maker model: the build is a pipeline you extend, and each output format is a maker you compose. electron-builder inverts that. You declare targets in a configuration object, and the tool decides the pipeline, including which helper binaries to download and how to compile native dependencies. Configuration over composition is the trade. You get a shorter path to signed installers on three platforms, and you give up the ability to insert custom steps at arbitrary points without working inside the tool's own extension points.

On the format axis, the same logic applies to nsis versus MSI on Windows. Both are listed targets, and the README does not rank them, so the choice is about your distribution channel and installer behaviour rather than about which one the project prefers.

There is a second alternative worth naming: building only on CI with Docker images. The README lists Docker images that build an Electron app for Linux or Windows from any host platform. That is not a competitor to electron-builder, it is a way of consuming it, and it is the answer when your developers are on macOS but your Linux artifacts have to be reproducible. The trade is that you now maintain a container image and its cache alongside your app, and the on-demand tool downloads have to survive inside that image.

One thing electron-builder does that neither the plugin model nor a hand-rolled script gives you for free is the electron-updater pairing. The README describes auto update as working out of the box, and the updater is versioned and released separately from the builder, which means the two can move independently and you should track both.

Licence, release cadence and the cost of staying current

The project is MIT licensed, and the repository's own package.json carries the same MIT identifier for the monorepo. MIT is permissive: you can use, modify and redistribute it, including in closed-source applications. This is not legal advice, and the practical question with a packaging tool is not the licence of the tool but the licences and terms of the helper binaries it downloads for you, such as signing tools and platform-specific packaging utilities. Those are separate artifacts with their own terms, and the README does not enumerate them.

The release cadence is visible in the feed: electron-builder 26.16.1 on 2026-09-07, 26.16.0 on 2026-09-02, and electron-updater 7.0.0-alpha.7 on 2026-09-02. The last push to the repository was on 2026-09-20. Two things follow. First, the project is moving: v27 is the current major line and the alpha updater series is a pre-release, so pinning exact versions in CI is worth the effort. Second, because the builder and the updater release independently, an upgrade to one does not imply the other moved.

The upgrade cost is concentrated in major versions. v27 requires Node.js 22.12.0, moves to native ESM and removes deprecated APIs, and the README directs you to two separate documents before you upgrade. The minor releases in the 26.x line look like the cheap path. If you have a long-lived release branch, budget for the Node floor and the ESM transition together rather than treating them as separate chores.

Editorial conclusion

Adopt electron-builder if you ship one Electron codebase to macOS, Windows and Linux and want signed installers plus update metadata without writing per-platform packaging scripts. Skip it if you need a plugin ecosystem for custom build steps, or if you cannot move to Node.js 22.12.0 for v27 and are not prepared to stay on the v26 line. Before upgrading, read the v27 breaking changes page and the v26 to v27 migration guide, then run electron-builder migrate-schema on a branch and diff the config it rewrites, because the migration document warns that v27 changes silent defaults as well as removing deprecated APIs.

Frequently asked questions

Official sources

1. electron-userland/electron-builder on GitHub
2. License: MIT
3. Project website
4. README
5. Releases