electron-builder

What this skill does

# electron-builder

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

## Quick Start

Install:
```bash
pnpm add electron-builder -D
pnpm add electron-updater  # If using auto-updates
```

Minimal config (`electron-builder.yml`):
```yaml
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`:
```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

```bash
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
```bash
export CSC_IDENTITY_AUTO_DISCOVERY=false
# Or in config: mac.identity: null
# For ad-hoc (ARM): mac.identity: "-"
```

### macOS: Notarization
```yaml
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
```yaml
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
```typescript
// 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)
```typescript
// 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.**

### Events
```typescript
autoUpdater.on("error", (err) => {});
autoUpdater.on("checking-for-update", () => {});
autoUpdater.on("update-available", (info) => {});
autoUpdater.on("update-not-available", (info) => {});
autoUpdater.on("download-progress", (progress) => {
  // .bytesPerSecond, .percent, .total, .transferred
});
autoUpdater.on("update-downloaded", (info) => {
  autoUpdater.quitAndInstall();
});
```

### Debugging
```typescript
import log from "electron-log";
autoUpdater.logger = log;
autoUpdater.logger.transports.file.level = "info";
```

For staged rollouts, custom updater instances, private repos, dev testing:
See [references/auto-update.md](references/auto-update.md)

## Publishing

### Quick GitHub Releases setup
```yaml
publish:
  provider: github
  releaseType: draft
```
Set `GH_TOKEN` env var (personal access token with `repo` scope).

### Quick S3 setup
```yaml
publish:
  provider: s3
  bucket: my-bucket-name
```
Set `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`.

### Quick Generic Server setup
```yaml
publish:
  provider: generic
  url: https://example.com/releases
```
Upload artifacts + `latest.yml` manually.

### Publish CLI behavior
| Condition | Default behavior |
|---|---|
| CI detected | `onTagOrDraft` |
| CI + tag pushed | `onTag` |
| npm script `release` | `always` |

### Release Channels
Version determines channel: `1.0.0` = `latest`, `1.0.0-beta.1` = `beta`

For all publishers (Bitbucket, GitLab, Keygen, Snap Store, Spaces), workflows, and advanced config:
See [references/publishing.md](references/publishing.md)

## Platform Target Configuration

### macOS
```yaml
mac:
  category: public.app-category.developer-tools
  hardenedRuntime: true
  darkModeSupport: true
  target: dmg
  entitlements: build/entitlements.mac.plist
  notarize: true
```

### Windows (NSIS)
```yaml
nsis:
  oneClick: true              # false for assisted installer
  perMachine: false
  allowToChangeInstallationDirectory: false
  createDesktopShortcut: true
  deleteAppDataOnUninstall: false
  include: build/installer.nsh  # Custom NSIS script
  differentialPackage: true
```

### Linux
```yaml
linux:
  category: Development
  desktop:
    MimeType: "x-scheme-handler/myapp"
  target:
    - AppImage
    - deb
    - snap
```

For all target options (DMG, PKG, MAS, MSI, AppX, Snap, Flatpak, portable, custom NSIS scripts):
See [references/platform-targets.md](references/platform-targets.md)

## Build Hooks

Execution order:
```
beforeBuild → beforePack → afterExtract → afterPack → [signing] →
afterSign → artifactBuildStarted → [build] → artifactBuildCompleted →
afterAllArtifactBuild
```

### Inline (JS/TS config)
```javascript
module.exports = {
  afterSign: async (context) => {
    if (context.electronPlatformName === "darwin") {
      await notarize(context);