electron-builder-packaging

name	electron-builder-packaging
description	Package and distribute an Electron app — electron-builder/Forge, per-OS installers (dmg/nsis/AppImage/deb), code signing (Apple Developer ID + notarization, Windows Authenticode), and native-module rebuilds. USE WHEN configuring builds, signing, notarizing, or producing installers for macOS/Windows/Linux.
cluster	electron
version	1.0.0
origin	skill-clusters (original)

Electron Builder & Packaging

Turning the app into signed, installable artifacts per OS. Two main tools: electron-builder (declarative build config, most common) and Electron Forge (plugin-based). Pick one.

Targets per OS

OS	Installers	Signing
macOS	dmg, zip	Apple Developer ID + notarization (required for Gatekeeper)
Windows	nsis, msi, appx	Authenticode code-signing cert (EV reduces SmartScreen friction)
Linux	AppImage, deb, rpm, snap	optional (repo/GPG)

macOS signing + notarization (the gotcha)

• Sign with a Developer ID Application cert, enable the hardened runtime, and provide entitlements (e.g. JIT/allow-unsigned-executable-memory only if truly needed).
• Notarize (notarytool) and staple the ticket — unnotarized apps are blocked on modern macOS.
• electron-builder runs this if afterSign/notarize + Apple API key creds are configured.

Windows

• Sign the installer and the app .exe with an Authenticode cert; timestamp it.
• NSIS one-click vs assisted; per-machine vs per-user install.

Native modules

• Native addons must match Electron's ABI — electron-builder runs electron-rebuild / uses prebuilds at pack time. Mismatch → "module did not self-register" at runtime (electron-core).
• Keep asar on, but asarUnpack native .node binaries and other files needing real paths.

CI

• Build the matrix on real (or VM) macOS/Windows/Linux runners; inject signing certs/keys via CI secrets, never commit them.
• Output a versioned feed for electron-auto-update.

Guardrails

• Always sign and (macOS) notarize before distributing — and before enabling auto-update.
• Keep signing keys in CI secrets / a vault; never in the repo.
• Match native modules to Electron's ABI; asarUnpack binaries.
• Version artifacts to feed electron-auto-update.