Skip to main content

v27 Breaking Changes

Read this before upgrading to v27

v27 moves the entire electron-builder ecosystem to native ES modules, raises the minimum runtime to Node.js 22.12.0, and hard-deletes the deprecated APIs that accumulated since v22. Every breaking change in the release is catalogued in this section.

Most projects need only a Node.js bump plus one command. Run the automated migrator and follow the step-by-step migration walkthrough →.

This section is the canonical reference for what changed in v27. For the how — the ordered upgrade steps, the automated migrator, and the checklist — see the v26 → v27 migration walkthrough. New, additive features are listed on What's New in v27.

  • The build() API is unchanged; configuration keys that were renamed or restructured are rewritten automatically by migrate-schema and keep their v26 behavior, and exported types that survive keep their shape.
  • CJS require() continues to work without code changes on supported Node.js versions.
  • Every config-level breaking change that has a mechanical v27 equivalent is rewritten automatically by electron-builder migrate-schema (look for the Auto ✓ marker on the Config page). The config keys it cannot rewrite, squirrelWindows.customSquirrelVendorDir and a custom NSIS bundle in nsis.customNsisBinary / customNsisResources, are reported with a warning. Runtime, CLI, env-var, and behavior changes require manual action — see what migrate-schema does and does not do.
Run the automated migrator first
electron-builder migrate-schema # apply changes in place
electron-builder migrate-schema --dry-run # preview only

This handles every change marked Auto ✓ on the Config page. See the walkthrough for flags and serialization caveats.


Breaking changes at a glance​

The changes are split by where you fix them. Each page opens with its own at-a-glance table, and each entry says how the build tells you about it.

PageWhat's on it
ConfigRemoved, renamed and restructured config keys. migrate-schema rewrites most of them; any left behind fail the build.
Build & PublishNode.js and CLI, toolsets and environment variables, dependency collection and validation, signing checks, publishing and update metadata, Flatpak build tooling.
Runtime (Shipped App)What changes on users' machines: auto-update defaults and the electron-updater API, macOS entitlements and DMG, NSIS file associations, the Linux launcher, Flatpak and Snap defaults.
Developer-OnlyOnly if you write code against electron-builder: ESM packaging, the programmatic and plugin APIs, build hooks and custom signers, custom NSIS and maintainer scripts, type exports.

How v27 tells you about breaking changes​

Most v27 breaking changes announce themselves when a build runs into them:

  • Removed or moved config keys fail the build with one error that lists each key, its replacement and a link to its section.
  • Most build and publish changes fail the build or log a warning with a link to their section: missing dependencies, mismatched native binaries, removed environment variables, signing-key and publisher checks, Flatpak and Snap defaults, and more.
  • Some runtime defaults get an advisory from migrate-schema (nsis-web installers, per-machine NSIS builds, macOS entitlements, feed URLs with a query string, feeds over plain http), the build warns when no file of the app mentions autoUpdater.crossOriginHeaders, and electron-updater logs a warning when app code uses a changed API.

The quickest way through an upgrade is:

  1. Run migrate-schema.
  2. Run a normal build.
  3. Run a publishing build: the signing-key, S3 and update-feed checks only run when publishing.
  4. Follow the links in any errors or warnings.
  5. Check the list below: those changes won't tell you.

Changes that won't tell you​

Silent​

ChangeAffects you ifPage
DMG filesystem defaults to APFSYou support macOS older than 10.13 (High Sierra)Runtime
http-parser dropped from the default pacman dependsYour Arch package relies on http-parserRuntime
Linux targets launch through a *-launcher script; AppImage adds --no-sandbox only for the legacy FUSE2 runtimeYou ship a custom .desktop file, AppArmor profile or MIME handler, or need the Chromium sandbox off in an AppImageRuntime
Windows update signature verification fails closedYour users' machines may block PowerShell (AppLocker / WDAC), or your update installers are catalog-signed. Updates fail only on those machinesRuntime
NSIS update installers must carry the update's versionYou change an installer's version resource after the build, or write latest.yml yourself, without signing update manifests. Updates fail with ERR_UPDATER_INSTALLER_VERSION_MISMATCHRuntime
An nsis-web installer started as an update needs a package fileYou write the latest.yml of an nsis-web release yourself, without its packagesRuntime
Linux: gksudo, kdesudo and beesu refuse unsafe installer pathsYour users' machines may lack polkit (pkexec), and the deb/rpm/pacman update's cache path (artifactName, updaterCacheDirName, the user name) can hold characters other than letters, digits and ._/+,:=@%-. Updates fail only on those machinesRuntime
The nsis-web installer verifies its app packageYou run one web installer with a --package-file from another buildRuntime
verifyUpdateCodeSignature renamed (shim until v28)Your app sets verifyUpdateCodeSignature, or a subclass redeclares _verifyUpdateCodeSignatureRuntime
macOS names are no longer NFD-normalizedYour product name has accented characters and external tooling matches the bundle filenameBuild
An empty GitHub tagNamePrefix is honoredYou set tagNamePrefix: "" (v26 still tagged v1.2.3)Config
npm run release no longer publishesYour release script relied on its name to publishBuild
The embedded update feed follows target-level publishYou set publish on a target (e.g. nsis.publish), or the first provider has publishAutoUpdate: falseBuild
latest*.yml drops the top-level path / sha512App code or tooling reads info.path / info.sha512, or you still ship electron-updater 2.15 or olderBuild
NSIS customInstallMode macro guard casingYour custom NSIS script defines customInstallmode (lowercase m)Developer

Info log only​

ChangeAffects you ifPage
Toolsets resolve to "latest"; Wine is the host installYou build Windows targets on macOS (install Wine), or need a legacy bundleBuild
RPM builds use a bundled rpmbuildYour rpm build relies on host rpm macros (~/.rpmmacros, /etc/rpm)Build
Azure Trusted Signing uses signtool /dlibYou need the legacy PowerShell signing pathBuild
node_modules are filtered by cpu / os on every buildYou bundle a cross-arch or cross-OS optional binary on purposeBuild
electron / electron-builder are excluded from the copied node_modulesYou need electron-builder inside the appBuild

Silent in the common case​

ChangeAffects you ifPage
macOS default entitlements drop allow-unsigned-executable-memoryYour app needs that entitlement. Only the library-validation part gets a build warningRuntime
S3 publishing needs awsCredentials.sourceYou publish to S3. Builds that don't publish don't check itBuild
macOS: the ASAR integrity digest is embeddedYou merge separately built x64 and arm64 apps with @electron/universal yourself. The build only warns when you have an afterPack hookRuntime

What migrate-schema covers​

v27 adds electron-builder migrate-schema, which rewrites your config to v27 form in place and auto-migrates static (json/json5/yaml/package.json) and programmatic (.js/.ts/.cjs/.mjs) configs. TOML configs are parsed and the required changes printed, but not written. See the walkthrough for flags and the before/after of every rewrite.

It rewrites every entry marked Auto ✓ on the Config page: removed keys (electronCompile, framework/nodeVersion/launchUiVersion, disableDefaultIgnoredFiles, appImage.systemIntegration, linux.syncDesktopName, mac.gatekeeperAssess), the nativeModules, asar (root and platform-level), fileOptions (root and platform-level), mac.sign, mac.universal, win.sign, electronGet, and snapcraft restructurings, GitHub vPrefixedTagName → tagNamePrefix, includePdb → fileOptions.excludedExts, helper-bundle-id, squirrelWindows.noMsi, root-level directories in package.json, null toolsets.* values, and the retired toolsets.appimage pins "1.0.2" (→ "1.0.3") and "1.2.0" (→ "1.2.1"). Values with no v27 equivalent (for example nativeRebuilder: "legacy" or electronDownload.strictSSL) are dropped with a warning.

It warns but leaves in place what cannot be rewritten mechanically: squirrelWindows.customSquirrelVendorDir, a custom NSIS bundle in customNsisBinary / customNsisResources (→ toolsets.nsis; it does move customNsisBinary.debugLogging → installerDebugLogging), a custom mac.sign signer combined with sibling signing options, an includePdb value v26 rejected, and, in JS/TS configs, platform-level asarUnpack next to root-level ASAR options, an includePdb whose value is not a literal, or, for includePdb: true, a platform section the codemod cannot read or a root fileOptions.excludedExts with an element it cannot read (a spread, an identifier, a call; readable platform lists still get "!pdb").

It prints an advisory (without changing the config) for runtime defaults and behavior changes you should check: an nsis-web target (disableWebInstaller), nsis.perMachine or nsisWeb.perMachine set to true (per-machine NSIS updates), a custom win.sign.sign hook without win.sign.publisherName, unless win.verifyUpdateCodeSignature is false (publisher name), a win.sign.publisherName entry that is not a distinguished name, e.g. a bare name (publisher name DN), win.sign: false / null or win.sign.publisherName: null, unless win.verifyUpdateCodeSignature is false (missing publisher name), a generic publish configuration whose url has a query string (update credentials), a publish feed over plain http to a host that is not loopback: a generic or custom url, a github protocol: "http" or an s3 endpoint without accelerate (update requests require https), forceCodeSigning (forceCodeSigning covers notarization and update manifests), a fileOptions.files pattern that names .pdb files (includePdb → fileOptions.excludedExts), and a mac/mas/masDev section that names no entitlements file (tightened default entitlements).

It does not touch anything outside the config: CLI flags, environment variables, custom NSIS scripts, Linux maintainer scripts, app code using the electron-updater API, or plugins using PlatformPackager. Every change on the Build, Runtime and Developer pages is a manual step.