| 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.
