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)

Searching Database…

14.7K ·GitHub
Electron-builder
Что это?Electron-builder упаковывает приложение Electron в готовые к распространению установщики для macOS, Windows и Linux, а поддержка автообновлений включена по умолчанию.
Это инструмент командной строки или то, что я импортирую в код?И то, и другое: вы настраиваете его через блок 'build' в package.json и запускаете из командной строки, а также он предоставляет полноценный программный API (TypeScript) для сборок через скрипты.
Как добавить его в моё приложение Electron?Начните с официального electron-quick-start, добавьте electron-builder, заполните стандартные поля package.json, блок 'build' и иконки, добавьте скрипты 'app:dist' и 'app:dir', затем запустите 'yarn app:dist', чтобы получить установщики.
Нужна ли мне сначала определённая версия Node.js?Да: v27 требует Node.js 22.12.0 или новее, а если ваш проект использует режим PnP в Yarn 3, нужно переключиться на связывание node-modules в .yarnrc.yaml, чтобы electron-builder работал.
Нужен ли мне сертификат подписи кода перед выпуском?Для боевого релиза — да: electron-builder всё равно упакует неподписанное приложение, но прямо предупредит, что его нужно подписать перед выпуском, а переход с v26 приносит ломающие изменения, для которых нужна миграция.
Можно ли собрать установщики для Windows и Linux на Mac или нужна каждая ОС отдельно?Не нужна каждая целевая ОС под рукой: electron-builder поставляется с Docker-образами, которые позволяют собирать цели для Linux или Windows с любой хост-системы, а нужные инструменты подписи и упаковки он скачивает автоматически.
Какие форматы вывода он может создавать?На разных платформах он может создавать архивы 7z/zip/tar, macOS dmg/pkg/mas, Linux AppImage/snap/deb/rpm/pacman/apk, а для Windows — установщики NSIS, портативные exe, AppX, MSI и пакеты Squirrel.Windows.
Куда можно опубликовать собранное приложение для автообновлений?Он может публиковать артефакты напрямую в GitHub Releases, Amazon S3, DigitalOcean Spaces или Bintray, а к ним затем обращается механизм автообновления, чтобы доставлять обновления.
Умеет ли он работать с нативными аддонами Node для Electron?Он компилирует нативные зависимости для продакшена под установленную версию Electron и предоставляет скрипт 'electron-builder install-app-deps', который запускается после установки и автоматически поддерживает их в синхронизации.
Какие шаблоны хорошо работают с ним?Стартовые шаблоны от сообщества, такие как electron-react-boilerplate, electron-vue-vite, vite-electron-builder и electronjs-with-nextjs, построены на основе 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