What's New in v27
electron-builder v27 is a major release: it moves the entire ecosystem to native ES modules, raises the minimum runtime to Node.js 22.12.0, adds several new capabilities, and quietly changes a handful of defaults. This page is the front door — a short tour of what's new, plus the silent behavior changes most likely to trip you up.
Upgrading an existing project?
Run electron-builder migrate-schema to auto-apply the config-key changes; the table below is what it does not do for you. For the ordered upgrade steps, follow the v26 → v27 walkthrough; for the full catalogue of everything that changed, see v27 Breaking Changes.
New in v27
- MSIX target (beta) — a
win.target: "msix"alongside AppX, producing.msix/.msixbundle/.msixuploadartifacts with modern manifest features (Package Integrity, Windows Services). Purely additive; the defaultwinCodeSigntoolset is MSIX-capable. - Cloudflare R2 publish provider — an opt-in, S3-compatible
provider: "r2"target with matching electron-updater support. Credentials come fromCF_R2_ACCESS_KEY_ID/CF_R2_SECRET_ACCESS_KEY. - Windows PKCS#11 & HSM code signing — two new
win.signmodes (beta):pkcs11(cross-platform viaosslsigncode— sign Windows apps from macOS/Linux CI with no Windows VM) andhsm(Windows CSP / FIPS token). - DMG
ULMO/ LZMA format — a newdmg.format: "ULMO"for LZMA-compressed images (macOS 10.15+), typically ~30% smaller than the defaultUDZO. Additive; the default format is unchanged. - electron-updater
allowUnverifiedLinuxPackages— a newAppUpdaterflag to enforce GPG signature checks when installing.deb/.rpmauto-updates. Additive; defaults totrue(historical behavior). migrate-schemaCLI — a new command that rewrites your v26 config to v27 form in place, covering both static (json/json5/yaml/package.json) and programmatic (.js/.ts/.cjs/.mjs) configs.- Native ESM + Node.js >=22.12 — every package now ships as native ES modules. On Node.js 22.12.0+ both
importand CJSrequire()continue to work with no code changes.
New defaults and behavior changes you may trip over
These are the runtime and default changes that migrate-schema does not rewrite for you — no config key changed, so the migrator can't see them. Skim the list; each row deep-links to the full explanation.
| Change | One-line impact | Details |
|---|---|---|
| Node.js >=22.12.0 required | The build fails on older Node — bump your local runtime, CI, and Docker images. | → |
Toolsets resolve to "latest" | Unset / "latest" now fetch the newest bundle (winCodeSign 1.3.0, FUSE3 AppImage, NSIS 3.12); pin "0.0.0" to restore a legacy bundle. | → |
| Wine is the host install | toolsets.wine defaults to "system": building Windows targets on macOS now needs Wine installed (brew install --cask wine-stable). | → |
| macOS default entitlements tightened | The bundled default grants only allow-jit; apps loading native modules or frameworks signed by another Team ID (or unsigned) must add disable-library-validation back in build/entitlements.mac.plist. | → |
| Missing production dependencies fail the build | An unresolvable production dependency is now an error instead of a warning; allowMissingDependencies: true restores warn-only. | → |
extraFiles / extraResources to validated | An absolute to, or one escaping the output dir, now throws. | → |
Windows publisherName validated | A win.sign.publisherName that does not match the signing certificate now fails the build. | → |
| Suffixed update channels expand | With generateUpdatesFilesForAllChannels, a channel such as beta-arm64 now also writes alpha-arm64.yml. | → |
node_modules arch/os-filtered every build | Dependencies whose cpu / os mismatch the target are now excluded from the app (was effectively universal-macOS only). | → |
arch: "all" -> x64 + arm64 | "all" no longer includes ia32 — request ia32 explicitly. Windows ia32 / Linux armv7l fail fast on Electron 44+. | → |
electron / electron-builder excluded from node_modules | Listing them in dependencies no longer errors — they're dropped from the copied node_modules; tune the set via ignoredProductionDependencies. | → |
DMG filesystem defaults to APFS | New images use APFS (was HFS+); set dmg.filesystem: "HFS+" only for pre-10.13 macOS compatibility. | → |
disableWebInstaller defaults to true | electron-updater warns now (v27) and blocks in v28 for NSIS web-installer updates unless you opt in with disableWebInstaller: false. | → |
latest*.yml drops top-level path/sha512 | Update metadata now carries only files[]; read info.files[0] and set electronUpdaterCompatibility if you still ship pre-2.16 updaters. | → |
| Bitbucket token without username -> Bearer auth | A BITBUCKET_TOKEN with no username is now sent as Bearer; set BITBUCKET_USERNAME if it's an app password / API token needing Basic auth. | → |
macOS productName / executableName validated | A name that would need filename sanitization now throws at build start instead of being silently rewritten. | → |
| NSIS file-association ProgID format changed | Associations now register under a unique generated ProgID; update custom NSIS scripts that hard-code the old name/extension. | → |
Linux .desktop runs a *-launcher script | Every Linux target launches via a generated <executableName>-launcher; the .desktop Exec points at it. Update custom .desktop / AppArmor / MIME tooling. | → |
AppImage --no-sandbox only for legacy FUSE2 | With the default FUSE3 runtime, --no-sandbox is no longer auto-added; set executableArgs: ["--no-sandbox"] if you need it unconditionally. | → |
Azure Trusted Signing uses signtool /dlib | The default winCodeSign 1.3.0 ships the ATS dlib payload, so ATS uses the faster path automatically; pin below 1.3.0 to force the legacy PowerShell path. | → |
note
This is the short list of high-traffic surprises. For the complete, authoritative catalogue — including config-key renames the migrator does handle — see v27 Breaking Changes.