/electron-builder

name: electron-builder
description: |
  Comprehensive guide for electron-builder (v26.x) packaging, code signing, auto-updates,
  and release workflows. Use when: (1) configuring electron-builder builds (electron-builder.yml
  or config.js/ts), (2) setting up macOS/Windows code signing or notarization, (3) implementing
  auto-updates with electron-updater, (4) publishing to GitHub Releases, S3, or generic servers,
  (5) configuring platform targets (NSIS, DMG, AppImage, Snap, PKG, MSI), (6) working with
  build hooks (beforePack, afterSign, afterAllArtifactBuild), or (7) using the programmatic API.
  Triggers on: electron-builder, electron-updater, code signing, notarize, NSIS, DMG, AppImage,
  auto-update, publish releases, build hooks, electron packaging, electron distribution.

electron-builder

Docs: https://www.electron.build (v26.8.x) Repo: https://github.com/electron-userland/electron-builder

Quick Start

Install:

pnpm add electron-builder -D
pnpm add electron-updater  # If using auto-updates

Minimal config (`electron-builder.yml`):

appId: com.example.myapp
productName: My App
files:
  - "out/**/*"
  - "package.json"
mac:
  target: dmg
  category: public.app-category.developer-tools
win:
  target: nsis
linux:
  target:
    - AppImage
    - deb
publish:
  provider: github

Build scripts in `package.json`:

{
  "scripts": {
    "build:mac": "electron-builder --mac",
    "build:win": "electron-builder --win",
    "build:linux": "electron-builder --linux",
    "build:all": "electron-builder -mwl",
    "release": "electron-builder --publish always"
  }
}

CLI Reference

electron-builder                    # Build for current platform
electron-builder -mwl              # Build for all platforms
electron-builder --mac dmg         # macOS DMG only
electron-builder --win nsis:ia32   # Windows NSIS 32-bit
electron-builder --linux deb tar.xz
electron-builder --dir             # Unpacked dir (test builds)
electron-builder -p always         # Build and publish

# Architecture flags
--x64  --ia32  --armv7l  --arm64  --universal

# CLI config overrides
-c.extraMetadata.foo=bar
-c.mac.identity=null
-c.nsis.unicode=false

# Publish existing artifacts
electron-builder publish -f dist/*.exe -c electron-builder.yml

Publish flag values: `onTag` | `onTagOrDraft` | `always` | `never`

Configuration

Config locations (checked in order): 1. `package.json` > `"build"` key 2. `electron-builder.yml` (default, recommended) 3. `electron-builder.json` / `.json5` / `.toml` 4. `electron-builder.config.js` / `.ts` 5. CLI: `--config <path>`

**Do NOT name JS config `electron-builder.js`** — conflicts with package name.

For full configuration options, file patterns, macros, icons, and directory settings: See [references/configuration.md](references/configuration.md)

Essential Config Properties

| Property | Default | Description | |---|---|---| | `appId` | `com.electron.${name}` | **Do not change once deployed.** Used as bundle ID (macOS) and AUMID (Windows). | | `productName` | package.json name | Display name (allows spaces) | | `compression` | `"normal"` | `"store"` for fast test builds, `"maximum"` for release | | `asar` | `true` | Pack source into asar archive | | `files` | auto | Glob patterns for app source files | | `extraFiles` | — | Files copied outside asar (e.g. native addons) | | `extraResources` | — | Files copied to resources directory | | `forceCodeSigning` | `false` | Fail build if not signed |

File Macros

Available in `artifactName`, file patterns, and publish URLs: `${arch}`, `${os}`, `${platform}`, `${name}`, `${productName}`, `${version}`, `${channel}`, `${ext}`, `${env.VAR_NAME}`

Default Targets

| Platform | Default | |---|---| | macOS | DMG + ZIP | | Windows | NSIS | | Linux (cross) | Snap + AppImage (x64) | | Linux (native) | Snap + AppImage (current arch) |

Code Signing

Signing is automatic when configured. Core environment variables:

| Env | Description | |---|---| | `CSC_LINK` | Certificate path/URL/base64 (.p12/.pfx) | | `CSC_KEY_PASSWORD` | Certificate password | | `CSC_IDENTITY_AUTO_DISCOVERY` | `true`/`false` (macOS keychain auto-discovery) | | `WIN_CSC_LINK` | Windows cert (when cross-signing from macOS) | | `WIN_CSC_KEY_PASSWORD` | Windows cert password |

macOS: Disable signing

export CSC_IDENTITY_AUTO_DISCOVERY=false
# Or in config: mac.identity: null
# For ad-hoc (ARM): mac.identity: "-"

macOS: Notarization

mac:
  hardenedRuntime: true
  notarize: true    # or { teamId: "TEAM_ID" }

Requires `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID` env vars.

Windows: Azure Trusted Signing

win:
  azureSignOptions:
    publisherName: "CN=Your Company"
    endpoint: "https://eus.codesigning.azure.net"
    certificateProfileName: "your-profile"
    codeSigningAccountName: "your-account"

Requires `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`.

For complete code signing reference (CI setup, certificates, EV certs, cross-platform): See [references/code-signing.md](references/code-signing.md)

Auto Update (electron-updater)

Minimal setup

// main process
import electronUpdater, { type AppUpdater } from "electron-updater";

export function getAutoUpdater(): AppUpdater {
  const { autoUpdater } = electronUpdater;
  return autoUpdater;
}

const autoUpdater = getAutoUpdater();
autoUpdater.checkForUpdatesAndNotify();

**Do NOT call `setFeedURL()`** — `app-update.yml` is auto-generated at build time.

ESM Import (required workaround)

// CORRECT
import electronUpdater from "electron-updater";
const { autoUpdater } = electronUpdater;

// WRONG (may fail with ESM)
import { autoUpdater } from "electron-updater";

Auto-updatable targets

• macOS: DMG
• Windows: NSIS
• Linux: AppImage, DEB, Pacman (beta), RPM

**macOS apps MUST be signed** for auto-update. **Squirrel.Windows NOT supported.**

E