electron-builder README

The project's README from github.com/electron-userland/electron-builder. As one markdown file: README.md.

electron-builder npm version downloads per month

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

Always looking for community contributions! 👀 Setting up a dev environment is easy to do 🪩

Sponsors

WorkFlowy
Notes, Tasks, Projects.
All in a Single Place.

Tidepool
Your gateway to understanding your diabetes data

Keygen
An open, source-available software licensing and distribution API

ToDesktop
ToDesktop: An all-in-one platform for building and releasing Electron apps

Dashcam
Dashcam: Capture the steps to reproduce any bug with video crash reports for Electron.

Documentation

See the full documentation on electron.build.

Question Answer
“I want to configure electron-builder” See options
“I found a bug or I have a question” Open an issue
“I want to support development” Donate

Requirements

Node.js >=22.12.0 is required for v27.

⚠️ Upgrading from v26? v27 is a major release with breaking changes (native ESM, Node >=22.12, and removed deprecated APIs). Start with What's New in v27 for the highlights and the silent default changes, then read the full breaking changes before upgrading.

Then run the automated migration command — it rewrites your config in place:

electron-builder migrate-schema

Step-by-step walkthrough: v26 → v27 migration guide · electron.build/docs/migration/v26-to-v27

Installation

yarn add electron-builder --dev
// or npm, pnpm, bun

Note for Yarn 3

Yarn 3 uses PnP by default, but electron-builder still needs node-modules (ref: yarnpkg/berry#4804). Add configuration in the .yarnrc.yaml as follows:

nodeLinker: "node-modules"

This instructs Yarn to use node-modules instead of PnP.

Quick Setup Guide

electron-quick-start is the official minimal starter for a new Electron application.

  1. Clone the starter and add electron-builder:

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

  2. Specify the standard fields in the application package.json — name, description, version and author.

  3. Specify the build configuration in the package.json as follows:

    "build": {
  "appId": "your.id",
  "mac": {
    "category": "your.app.category.type"
  }
}

    See all options. Option files to indicate which files should be packed in the final application, including the entry file, maybe required. You can also use separate configuration files, such as js, ts, yml, and json/json5. See read-config-file for supported extensions. JS Example for programmatic API

  4. Add icons.

  5. Add the scripts key to the development package.json:

    "scripts": {
  "app:dir": "electron-builder --dir",
  "app:dist": "electron-builder"
}

    Then you can run yarn app:dist (to package in a distributable format (e.g. dmg, windows installer, deb package)) or yarn app:dir (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 package.json.

  6. If you have native addons of your own that are part of the application (not as a dependency), set nativeModules.nodeGypRebuild to true.

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.

Programmatic Usage

TypeScript types are provided and can be found here. See the full programmatic usage guide.

// ESM (recommended)
import { build, Platform } from "electron-builder"

await build({
  targets: Platform.MAC.createTarget(),
  config: {
    // build options — see https://www.electron.build/
  }
})

// CommonJS — also works on Node >=22.12.0
const { build, Platform } = require("electron-builder")

build({ targets: Platform.MAC.createTarget(), config: {} })
  .then(() => { /* done */ })
  .catch(console.error)

Community Boilerplates

Debug

Set the DEBUG environment variable to debug what electron-builder is doing:

DEBUG=electron-builder

FPM_DEBUG env to add more details about building linux targets (except snap and appimage).

DEBUG_DMG=true env var to add more debugging/verbosity from hdiutil (macOS).

:::tip[Windows cmd] On Windows the environment variable is set using the set command.

set DEBUG=electron-builder

:::

:::tip[PowerShell] PowerShell uses different syntax to set environment variables.

$env:DEBUG = "electron-builder"

:::

If you've identified a bug and want to report it, use electron/minimal-repro to create a minimal reproduction case. Attaching one to your issue significantly speeds up diagnosis.

Donate

This open source work is accomplished during free time. If you'd like to have more time invested in it, please consider donating.

electron-builder (electron-userland/electron-builder)

auto-update
Searching Database…

14.7K ·GitHub
Electron-builder
What is this?Electron-builder packages an Electron app into ready-to-distribute installers for macOS, Windows, and Linux, with auto-update support built in out of the box.
Is this a CLI tool or something I import into my code?Both: you configure it through a 'build' block in package.json and run it from the command line, but it also ships a full TypeScript/programmatic API for scripted builds.
How do I add it to my Electron app?Start from the official electron-quick-start, add electron-builder, fill in the standard package.json fields plus a 'build' config and icons, add 'app:dist'/'app:dir' scripts, then run 'yarn app:dist' to produce installers.
Do I need a specific Node.js version first?Yes, v27 requires Node.js 22.12.0 or newer, and if your project uses Yarn 3's PnP mode you need to switch to node-modules linking in .yarnrc.yaml for electron-builder to work.
Do I need a code-signing certificate before shipping?For a production release yes; electron-builder will still package an unsigned app, but it explicitly tells you to sign it before shipping, and upgrading from v26 brings breaking changes you need to migrate for.
Can I build Windows and Linux installers from a Mac, or do I need each OS separately?You don't need every target OS on hand: electron-builder ships Docker images that let you build Linux or Windows targets from any host, and it downloads the required signing/packaging tools automatically.
What output formats can it produce?Across platforms it can generate 7z/zip/tar archives, macOS dmg/pkg/mas, Linux AppImage/snap/deb/rpm/pacman/apk, and Windows NSIS installers, portable exe, AppX, MSI, and Squirrel.Windows packages.
Where can I publish the built app for auto-updates?It can publish artifacts directly to GitHub Releases, Amazon S3, DigitalOcean Spaces, or Bintray, which the auto-updater then checks against to deliver updates.
Does it handle native Node addons for Electron?It compiles native production dependencies against your installed Electron version and provides an 'electron-builder install-app-deps' postinstall script to keep them in sync automatically.
What boilerplates work well with it?Community starters like electron-react-boilerplate, electron-vue-vite, vite-electron-builder, and electronjs-with-nextjs are built around electron-builder.
What are similar projects?electron-react-boilerplate, dsh_desktop, nub, stemkit, nativefier, Lepton, buildkit, electron-vue
Which topics is it in?builder, contributions-welcome, help-wanted, snap, auto-update, electron-app, build-tool, deployment, package-manager, installer, github-actions, ci
Creator
electron-userland
Size
184.4 MB
Stars
14.7K
Updated
CommitOct 17Release[email protected]Sep 26
Age
11y
Commits · 90 Days