Packaging and Distribution for Desktop Platforms

electron-builder is the standard tool for packaging Electron apps into distributable installers. Its configuration lives in package.json under the "build" key, specifying app metadata (appId, productName), icon paths, and per-platform target formats.

electron-builder supports macOS (dmg and zip), Windows (nsis installer), and Linux (AppImage and deb). You can target multiple platforms in a single build command or configure CI to build each platform on its native runner for best compatibility.

macOS requires code signing with an Apple Developer certificate for Gatekeeper to allow users to open the app without a security warning. electron-builder reads your certificate from the macOS Keychain during the build process and signs all binaries automatically.

Beyond code signing, modern macOS also requires notarization — submitting the app to Apple's notarization service, which scans for malware and issues a ticket. electron-builder can automate notarization via electron-notarize, and users on macOS 10.15+ will be blocked without it.

Windows requires an Authenticode certificate from a trusted Certificate Authority (CA) for SmartScreen to trust your installer. Without signing, users see a "Windows protected your PC" warning. Extended Validation (EV) certificates eliminate the warning immediately, while standard OV certificates build trust over time.

After a successful build, electron-builder writes platform-specific installers to the dist/ directory. You'll find the DMG or zip for macOS, the NSIS .exe for Windows, and the AppImage or .deb for Linux, along with a latest.yml (or latest-mac.yml) auto-update manifest.

Electron apps need icons in platform-specific formats: a 512x512 PNG for Linux, an ICNS file (multi-resolution) for macOS, and an ICO file (multi-resolution) for Windows. electron-builder can generate all formats from a single 1024x1024 PNG using the --icon flag.

The electron-updater package integrates with electron-builder to provide automatic updates. Publish your builds to GitHub Releases or S3, and electron-updater can check for updates on startup, download the delta update in the background, and prompt the user to restart.

Call autoUpdater.checkForUpdatesAndNotify() in main.js after the app is ready. electron-updater fetches the latest.yml manifest from your publish target, compares versions, and if an update is available, downloads it and shows a native notification when ready to install.

electron-builder bundles your application's JavaScript files into a single ASAR archive (similar to a tar file) for distribution. This improves startup performance by reducing file system lookups and makes it harder (but not impossible) to inspect your source code directly.

Native Node.js modules (.node files) cannot be loaded from inside an ASAR archive — they must be unpacked to the file system. Configure asarUnpack in electron-builder to list native module patterns, which places them in the app.asar.unpacked directory alongside the archive.

Why is notarization required for macOS distribution beyond just code signing?

Distributing an Electron app involves configuring electron-builder targets, signing the code for both macOS (with notarization) and Windows (Authenticode), and optionally setting up auto-updates with electron-updater. The ASAR archive bundles your app for distribution, with native modules unpacked separately. A solid CI/CD pipeline handles these steps automatically per platform.