repository·master·Indexed 12 days ago
https://github.com/electron-userland/electron-builderA complete solution for packaging and building Electron applications for macOS, Windows, and Linux, featuring out-of-the-box support for auto-updates. Includes tools like electron-updater for automatic updates, electron-publish for artifact distribution, and support for various targets including NSIS, AppImage, Snap, and Squirrel.Windows.
electron-publish is a package that is part of the electron-builder ecosystem. It is designed to handle the publishing of build artifacts. While it is integrated into the main electron-builder workflow, it can also be used as a standalone tool for publishing artifacts.electron-builder supports multiple Linux package formats. You should choose a target based on your distribution method and target audience:
snapd). (Default)flatpak).The electron-forge-maker-nsis package provides an NSIS target for projects using Electron Forge.
Important Recommendation: It is highly recommended to build Electron Forge projects using electron-builder directly instead of using this maker. Using electron-builder directly ensures full support for critical features including:
files configuration key).Version 27 introduced several new capabilities:
win.target: "msix" to produce .msix, .msixbundle, or .msixupload artifacts with modern manifest features.provider: "r2" target. Requires CF_R2_ACCESS_KEY_ID and CF_R2_SECRET_ACCESS_KEY environment variables.win.sign modes: pkcs11 (cross-platform via osslsigncode) and hsm (Windows CSP / FIPS token).ULMO / LZMA format: Use dmg.format: "ULMO" for LZMA-compressed images (macOS 10.15+), which are typically ~30% smaller than the default UDZO.allowUnverifiedLinuxPackages: A new AppUpdater flag to enforce GPG signature checks for .deb / .rpm auto-updates (defaults to true).import and CJS require() are supported.The electron-forge-maker-nsis-web package provides an NSIS web target for projects using Electron Forge.
Important Note: It is highly recommended to build Electron Forge projects using electron-builder directly instead of using this maker. Many critical features are only supported when using electron-builder directly, including:
files configuration key).electron-builder-squirrel-windows package is a plugin for electron-builder that enables the creation of Squirrel.Windows installers for Windows applications. It allows you to leverage the Squirrel.Windows installation framework within your electron-builder configuration.MSI-Wrapped is a hybrid packaging approach that wraps a standard NSIS .exe installer inside a minimal MSI shell. This allows you to leverage the full customization capabilities of NSIS while providing an MSI package that enterprise IT teams can deploy via tools like Group Policy, SCCM, or Intune.
Build hooks allow you to execute custom code at specific stages of the electron-builder lifecycle. This is useful for modifying app bundles, performing custom code signing, uploading debug symbols, or integrating with external services like Sentry.
Hooks are executed serially for each platform/architecture combination. If a hook is asynchronous, electron-builder will await its completion before proceeding. If a hook throws an error, the entire build process will fail.
Key Lifecycle Stages:
beforeBuild (before native deps are installed).beforePack (before files are copied), afterExtract (after Electron binary extraction), afterPack (after files are packaged, but before signing).afterSign (after signing, but before distributable creation).artifactBuildStarted, artifactBuildCompleted, and afterAllArtifactBuild (after all installers/images are finished).// Example of a simple hook in a JS config
module.exports = {
afterPack: async (context) => {
console.log("afterPack:", context.appOutDir)
}
}Because v27 requires Node.js >=22.12.0, you can continue using require() or switch to the preferred import syntax without breaking the integration. Both styles are supported natively.
// CJS require() — still works
const { build } = require("electron-builder")
// ESM import — now the preferred style
import { build } from "electron-builder"To ensure silent upgrades and prevent orphaned installations on Windows, you must keep the application identity constant across releases.
guid option.upgradeCode.Warning: Changing these values between releases will break the upgrade path for existing users.
To ensure desktop environments (GNOME, KDE, etc.) correctly link running windows to their launcher icons and taskbar entries, you must set the desktopName field in your root package.json.
Electron derives the window's WM_CLASS from this field. If desktopName is missing, electron-builder will log a warning, and the association may break because the fallback WM_CLASS might not match the installed .desktop filename.
// package.json
{
"desktopName": "com.example.MyApp"
}ASAR (Atom Shell Archive) is Electron's optimized archive format for bundling application source files. Because files inside ASAR are read through a virtual filesystem, native modules (.node files) or large binaries that require direct filesystem access cannot be run from within the archive.
To fix this, use the asar.unpack configuration option to provide glob patterns for files that should be placed in app.asar.unpacked/ instead of being bundled inside the ASAR archive.