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，并且内置自动更新功能，开箱即用。
这是命令行工具，还是我要在代码里导入的库？两者都是：你可以通过 package.json 中的 'build' 配置块进行设置，并在命令行中运行；同时它也提供完整的 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 或更高版本；如果你的项目使用 Yarn 3 的 PnP 模式，则需要在 .yarnrc.yaml 中切换为 node-modules 链接方式，electron-builder 才能正常工作。
发布前我需要代码签名证书吗？正式发布时需要。electron-builder 仍然可以打包未签名的应用，但它会明确提示你在发布前进行签名；此外，从 v26 升级到新版本会带来不兼容的变更，需要进行迁移。
我能在 Mac 上构建 Windows 和 Linux 的安装程序吗，还是需要分别使用每个操作系统？你不需要手头备有所有目标操作系统：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，自动更新程序随后会从这些位置检查并获取更新。
它能处理 Electron 的原生 Node 插件吗？可以。它会根据你已安装的 Electron 版本编译生产依赖中的原生模块，并提供 'electron-builder install-app-deps' 这个 postinstall 脚本，以自动保持它们同步。
有哪些启动模板适合与它配合使用？社区中的几个启动模板，如 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, vite-plus, nativefier, Lepton, buildkit
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.5 MB
Stars
14.7K
Updated
CommitOct 18Release[email protected]Sep 26
Age
11y
Commits · 90 Days