Skip to main content

Migrating from v26 to v27

This is the step-by-step walkthrough for upgrading a project from v26 to v27. For the authoritative catalogue of everything that changed, see v27 Breaking Changes →.

v27 migrates the entire electron-builder ecosystem to native ES modules, raises the minimum Node.js version to 22.12.0, and hard-deletes the deprecated APIs that accumulated since v22.

Don't upgrade without reading the breaking changes

Every breaking change — what's removed, renamed, restructured, and what action each requires — is catalogued on the v27 Breaking Changes page. Skim it before you start so nothing surprises you.

Most projects need only a Node.js version bump plus one command. The build() API is unchanged and CJS require() continues to work without any code changes on supported Node.js versions. Configuration keys that were renamed or restructured (win.sign, mac.sign, electronGet, asar, nativeModules, fileOptions, …) are rewritten for you automatically by migrate-schema in Step 1 — they keep the same runtime behavior. A few type exports were renamed or removed; see the breaking changes.

The upgrade is three steps:

  1. Run the automated migrator — rewrites your config to v27 form
  2. Update Node.js — to >=22.12.0
  3. Apply the manual steps — the few things the migrator can't do

Then walk the summary checklist.


Step 1: Run the automated migrator​

Run the built-in command to apply every config-level breaking change to your project automatically:

electron-builder migrate-schema # apply changes in place
electron-builder migrate-schema --dry-run # preview without writing (alias: -n)

This rewrites your electron-builder.json, electron-builder.yml, package.json (build key), or any other static config format in place. It also rewrites programmatic configs (.js/.ts/.cjs/.mjs) via an AST-located codemod that preserves comments, imports, functions, and formatting.

Without --config, it looks for a build object in package.json and then for electron-builder.{yml,yaml,json,json5,toml,js,cjs,mjs,ts} in the project root. If your config file has another name (for example one your build scripts pass as electron-builder --config my-config.cjs), pass the same path: electron-builder migrate-schema --config my-config.cjs. Pass --project-dir <dir> to specify the project root (default: current directory).

What it migrates automatically​

Config changeBeforeAfter
electronCompile removed"electronCompile": true(deleted)
disableDefaultIgnoredFiles removed"disableDefaultIgnoredFiles": true(deleted)
framework / nodeVersion / launchUiVersion removed"framework": "electron"(deleted)
npmSkipBuildFromSource removed"npmSkipBuildFromSource": true"nativeModules": { "buildDependenciesFromSource": false }
Native-module options grouped"npmRebuild": true"nativeModules": { "npmRebuild": true }
nativeRebuilder renamed"nativeRebuilder": "parallel""nativeModules": { "rebuildMode": "parallel" }
nativeRebuilder: "legacy" removed"nativeRebuilder": "legacy"(dropped with a warning — @electron/rebuild "sequential" applies)
appImage.systemIntegration removed"appImage": { "systemIntegration": "ask" }(deleted)
linux.syncDesktopName removed"linux": { "syncDesktopName": true }(deleted — always synced in v27)
Legacy asar keys"asar-unpack": "**/*.node""asar": { "unpack": ["**/*.node"] }
asarUnpack consolidated"asarUnpack": ["**/*.node"]"asar": { "unpack": ["**/*.node"] }
disableSanityCheckAsar moved"disableSanityCheckAsar": true"asar": { "disableSanityCheck": true }
disableAsarIntegrity moved"disableAsarIntegrity": true"asar": { "disableIntegrity": true }
asar: true removed"asar": true(deleted — absence means enabled)
Platform asarUnpack moved"asarUnpack": ["**/*.node"], "mac": { "asarUnpack": ["x/**"] }"asar": { "unpack": ["**/*.node"] }, "mac": { "asar": { "unpack": ["**/*.node", "x/**"] } } (root options merged in — a platform asar replaces the root one)
Keys with no effect under asar: false"asar": false, "asarUnpack": "x""asar": false
macOS signing fields → sign"mac": { "identity": "Developer ID...", "hardenedRuntime": true }"mac": { "sign": { "identity": "Developer ID...", "hardenedRuntime": true } }
signIgnore renamed"mac": { "signIgnore": ["**/*.txt"] }"mac": { "sign": { "ignore": ["**/*.txt"] } }
mac.type moved"mac": { "type": "development" }"mac": { "sign": { "type": "development" } }
gatekeeperAssess removed"mac": { "gatekeeperAssess": false }(deleted — @electron/osx-sign 2.x has no spctl --assess step)
v26 null = unset on mac options"mac": { "provisioningProfile": null }(deleted — the v27 option rejects null; identity: null is kept)
mac.universal fields → universal"mac": { "mergeASARs": true }"mac": { "universal": { "mergeASARs": true } }
files / extraResources / extraFiles → fileOptions"files": ["dist/**"], "mac": { "extraResources": ["r"] }"fileOptions": { "files": ["dist/**"] }, "mac": { "fileOptions": { "extraResources": ["r"] } }
Flat key next to the same fileOptions key"files": ["a/**"], "fileOptions": { "files": ["b/**"] }"fileOptions": { "files": ["b/**"] } (the fileOptions value takes precedence; warns)
includePdb: true → fileOptions.excludedExts"includePdb": true"fileOptions": { "excludedExts": ["default", "!pdb"] } (the default extensions except pdb; "!pdb" is also appended to a root or platform fileOptions.excludedExts that excludes .pdb files; also for "true" and 1, which v26 read as true)
includePdb: false → fileOptions.excludedExts"includePdb": false"fileOptions": { "excludedExts": ["default"] } (the v27 default, written out so that it keeps overriding an includePdb: true of another config layer, e.g. an extends parent; also for "false", 0 and null, which v26 read as false; next to an existing root fileOptions.excludedExts, includePdb is just removed)
electronDownload → electronGet"electronDownload": { "mirror": "https://m/" }"electronGet": { "mirrorOptions": { "mirror": "https://m/" } }
electronDownload fields with no v5 equivalent"electronDownload": { "strictSSL": false, "force": true }(dropped with a warning)
GithubOptions.vPrefixedTagName"vPrefixedTagName": false"tagNamePrefix": ""
GitHub empty tagNamePrefix (ignored by v26){ "provider": "github", "tagNamePrefix": "" }{ "provider": "github", "tagNamePrefix": "v" } (keeps your tag names; warns)
win.azureSignOptions → win.sign"win": { "azureSignOptions": { "endpoint": "…" } }"win": { "sign": { "type": "azure", "endpoint": "…" } }
win.signtoolOptions → win.sign"win": { "signtoolOptions": { "certificateFile": "…" } }"win": { "sign": { "type": "signtool", "certificateFile": "…" } }
Azure extra sign keys"win": { "azureSignOptions": { "ExcludeCredentials": "X" } }"win": { "sign": { "type": "azure", "additionalMetadata": { "ExcludeCredentials": "X" } } }
win.signExecutable: false"win": { "signExecutable": false }"win": { "sign": false }
win.signExecutable: true removed"win": { "signExecutable": true }(deleted — enabled by default)
win.signAndEditExecutable: true removed"win": { "signAndEditExecutable": true }(deleted — always enabled in v27)
win.signAndEditExecutable: false"win": { "signAndEditExecutable": false }"win": { "sign": false } (resource editing now always runs; warns)
Signing options under disabled signing"win": { "signExecutable": false, "signtoolOptions": { … } }"win": { "sign": false } (the unused block is dropped; warns)
snap → snapcraft"snap": { "confinement": "strict", "base": "core22" }"snapcraft": { "base": "core22", "core22": { "confinement": "strict" } }
helper-bundle-id moved"helper-bundle-id": "com.x.helper""mac": { "helperBundleId": "com.x.helper" }
squirrelWindows.noMsi inverted"squirrelWindows": { "noMsi": true }"squirrelWindows": { "msi": false }
Root-level directories moved{ "directories": { "output": "dist" } } (package.json root){ "build": { "directories": { "output": "dist" } } }
toolsets.*: null rejected"toolsets": { "wine": null }(deleted — unset resolves to "latest")
Retired appimage pin"toolsets": { "appimage": "1.0.2" }"toolsets": { "appimage": "1.0.3" }
Withdrawn appimage pin"toolsets": { "appimage": "1.2.0" }"toolsets": { "appimage": "1.2.1" }

It also warns without rewriting where there is no mechanical equivalent — squirrelWindows.customSquirrelVendorDir and a custom NSIS bundle in nsis.customNsisBinary / customNsisResources (see Step 3; it does move customNsisBinary.debugLogging → installerDebugLogging), a custom mac.sign signer next to sibling signing options, an includePdb value v26 rejected (e.g. "yes"), and, in JS/TS configs only, a 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 (e.g. win: sharedWin) — and prints advisories (never a rewrite) for an nsis-web target, nsis.perMachine or nsisWeb.perMachine set to true, a custom win.sign.sign hook without win.sign.publisherName, a win.sign.publisherName entry that is not a distinguished name (e.g. a bare name), win.sign: false / null or win.sign.publisherName: null without win.verifyUpdateCodeSignature: false, a generic publish configuration whose url has a query string, a publish feed over plain http to a host that is not loopback (update requests require https), a fileOptions.files pattern that names .pdb files, forceCodeSigning, and a mac/mas/masDev section that names no entitlements file. In a JS/TS config, the advisories read literal values only: a value computed when the config runs, such as a publish url from process.env, is not checked. The build itself warns about a plain-http feed and a generic feed url with a query string, whatever the value comes from. See what migrate-schema does and does not do.

Each row links to its full explanation on the v27 Breaking Changes page.

Serialization caveats​

  • JSON5 → JSON: when migrate-schema rewrites a .json5 file it produces valid JSON (no comments, standard quoting) and prints a warning. If preserving comments matters, apply the changes manually.
  • TOML: the toml npm package is read-only. migrate-schema detects TOML configs, prints the required changes, and exits without writing.
  • YAML: js-yaml preserves key order when round-tripping but does not preserve comments.
  • Programmatic configs (.js/.ts/.cjs/.mjs): rewritten in place when reducible to a single object literal; falls back to printing manual steps for dynamic function bodies, spreads, or computed keys, or when typescript is not installed.
  • snap base defaulting: when your old snap config has no base field, the tool assumes "core20" (v27's 1-to-1 migration target) and prints a warning so you can confirm or change it.

Step 2: Update Node.js​

v27 requires Node.js 22.12.0 or later — the version where Node's require(esm) support was stabilized, allowing both CJS and ESM consumers to use these packages without code changes.

Update your local environment:

# nvm
nvm install 22 && nvm use 22

# fnm
fnm install 22 && fnm use 22

Update CI (GitHub Actions):

- uses: actions/setup-node@v4
with:
node-version: '22'

Update your package.json engines field if you declare one:

{ "engines": { "node": ">=22.12.0" } }

Confirm your CI and Docker images run Node.js 22.12 or later:

FROM node:22-bookworm-slim

electron-builder's own Docker images for Linux builds have been updated and are available in both node 22 and 24 flavors: https://hub.docker.com/r/electronuserland/builder/tags

Building the flatpak target?

node:22-bookworm-slim includes no flatpak tools. Install them with apt-get install -y flatpak flatpak-builder fuse3: Debian 12's flatpak 1.14.10 and flatpak-builder 1.2.3 meet the requirements. The electronuserland/builder images with a date tag newer than -05.26 include the tools, but no runtime, and the images up to -05.26 include neither — see Flatpak in the Docker Images. A container also needs FUSE and user namespaces, or the options for unprivileged containers — see Building Flatpak Bundles in CI and Containers.

ESM/CJS — no code changes needed on Node >=22.12​

// CJS require() — still works
const { build } = require("electron-builder")

// ESM import — now the preferred style
import { build } from "electron-builder"

moduleResolution settings "node", "node16"/"nodenext", and "bundler" (recommended) all work. See Native ESM output for details.


Step 3: Apply the manual steps​

migrate-schema handles every config-level change except squirrelWindows.customSquirrelVendorDir and a custom NSIS bundle in nsis.customNsisBinary / customNsisResources. The following require manual action — each links to its full explanation:

  • Migrate off electron-compile to a modern bundler (electron-vite / esbuild / webpack), if you used electronCompile.
  • Add --publish explicitly to your release scripts — auto-publish is gone.
  • Update-manifest signing: it is required on publishing builds — run npx electron-builder create-update-key once, store the PEM base64-encoded on one line (base64 < update-private-key.pem | tr -d '\n') as a CI secret and expose it as ELECTRON_BUILDER_UPDATE_SIGN_KEY, or set updateManifest: false to keep publishing unsigned manifests (warned about on every build). Every pipeline that can publish a release needs the key.
  • forceCodeSigning: now also requires notarization and signed update manifests, and verifies signatures — if you set it, provide the notarization credentials (macOS) and the update-manifest signing key, also to builds that do not publish, or opt out explicitly with mac.notarize: false / updateManifest: false. macOS builds with it now fail on a non-mac host and in pull-request builds: pass -c.forceCodeSigning=false where they cannot sign.
  • Replace devMetadata / extraMetadata in the programmatic API with config.extraMetadata.
  • Replace --em.build / --em.directories CLI flags with -c / -c.directories.
  • linux.syncDesktopName is removed automatically by migrate-schema — the behaviour is now always on. Only if you had it set to false: set desktopName to control the installed .desktop filename (the migrator warns you).
  • Switch <%= var %> → ${var} in Linux maintainer scripts.
  • Update custom NSIS scripts that hard-code the old file-association ProgID.
  • Replace CI_BUILD_TAG with CI_COMMIT_TAG.
  • Replace toolset env-var overrides (APPIMAGE_TOOLS_PATH, ELECTRON_BUILDER_NSIS_DIR, USE_SYSTEM_WINE, …) with toolsets.X: { url, checksum }.
  • Validate toolset pins — defaults now resolve to "latest" (newest bundle); pin to "0.0.0" only if a legacy bundle is needed.
  • 32-bit builds: arch: "all" now expands to x64 + arm64 (was x64 + ia32) — request ia32 explicitly to keep it. Building Windows ia32 / Linux armv7l on Electron 44+ now fails fast; pin electronVersion to 43.x or earlier (supported until January 2027) or drop those targets.
  • macOS names: productName / executableName are now validated, not silently sanitized — if a build starts erroring on the name, choose one that needs no filename sanitization.
  • Bitbucket publishing: a token set without a username is now sent as Bearer auth — if BITBUCKET_TOKEN holds an app password / API token, also set BITBUCKET_USERNAME so Basic auth is used; genuine access tokens need no username.
  • S3 publishing: an explicit awsCredentials.source is now required — add awsCredentials: { source: "env" } to keep using AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, or { source: "profile", profile: "<name>" } if you relied on AWS_PROFILE, ~/.aws/credentials, ~/.aws/config + AWS_SDK_LOAD_CONFIG=1 or an SSO login. For a role assumed from an SSO profile via source_profile, use { source: "sso-role-chain", profile: "<role profile>" }. Set region explicitly for dotted bucket names.
  • node_modules arch/os filtering: dependencies are now cpu/os-filtered against the target on every build — a package whose cpu/os mismatches the target is excluded (was effectively universal-macOS-only). Re-include an intentionally cross-arch binary via fileOptions.extraResources / fileOptions.files.
  • .pdb files named in files: a fileOptions.files pattern that names .pdb files now includes the ones it matches (e.g. native/*.pdb, **/*.{node,pdb}), also in a configuration that extends this one — v26 excluded them unless includePdb was true. migrate-schema reports such patterns; to keep the .pdb files out, remove the pattern or add a negation such as !native/*.pdb after it.
  • macOS DMG: the DMG filesystem default is now APFS — set dmg.filesystem: "HFS+" only if you need pre-10.13 (High Sierra) compatibility.
  • electron-updater: disableWebInstaller now defaults to true — web-installer updates are rejected (ERR_UPDATER_WEB_INSTALLER_DISABLED) unless it is false. Installs made by a v27+ nsis-web installer opt in automatically; set disableWebInstaller: false only for web-installer installs without the resources/package-type marker (pre-v27 installers, custom scripts) or when switching from nsis to nsis-web. The nsis-web installer now verifies and installs its own copy of the app package and leaves a local package file in place; set nsisWeb.allowUnverifiedAppPackage: true only if you use one web installer with packages of other builds.
  • NSIS per-machine updates: per-machine builds set isAdminRightsRequired in the update info — their updates are started with elevate.exe; with autoInstallEvent: "onNextLaunch", per-machine apps call installPendingUpdateIfAvailable() to install a pending update.
  • electron-updater: update credentials stay on the feed's origin — if latest*.yml points downloads at another origin that needs your requestHeaders / addAuthHeader credentials or a token in the feed URL's query, serve the files from the feed origin or use pre-signed URLs. A custom provider returns its feed URL from Provider.feedBaseUrl, else the update check fails with ERR_UPDATER_FEED_BASE_URL_NOT_DECLARED.
  • electron-updater: the app chooses the headers sent to another origin — set autoUpdater.crossOriginHeaders before the first check (and before ready for an install at launch), else the update check fails with ERR_UPDATER_CROSS_ORIGIN_HEADERS_NOT_CONFIGURED: autoUpdater.crossOriginHeaders = () => [] sends none of your request headers to another origin than the feed; return the names of the ones an origin may receive to send them there.
  • electron-updater: update requests require https — an http feed, download or redirect to a host that is not loopback fails with ERR_UPDATER_INSECURE_FEED; set the publish url to https and keep the http URL redirecting to the https feed for installs that have not updated yet, for a test server on another machine, set autoUpdater.allowInsecureFeed = !app.isPackaged.
  • electron-updater: update manifests whose YAML aliases expand too far are rejected — only if a tool of your own writes or rewrites latest*.yml with YAML aliases (e.g. js-yaml dump without noRefs): write it without aliases, or installs fail the update check with ERR_UPDATER_INVALID_UPDATE_INFO. Bitbucket and Keygen report an unparsable manifest with that code too (was ERR_UPDATER_LATEST_VERSION_NOT_FOUND).
  • electron-updater: latest*.yml no longer includes legacy top-level path/sha512 — no action for updater >=2.16; migrate any app code reading info.path/info.sha512 to info.files[0], and set electronUpdaterCompatibility to a legacy-inclusive range only if you still ship 1.x–2.15 updaters.
  • Production dependencies: redundant production dependencies are excluded, not rejected — electron/electron-builder are excluded from the copied node_modules (was a hard error) and the ALLOW_ELECTRON_BUILDER_AS_PRODUCTION_DEPENDENCY env var is removed (if you used it to bundle electron-builder, override ignoredProductionDependencies without that name); tune the set via ignoredProductionDependencies (e.g. add bundler-inlined deps like react). electron-prebuilt/electron-rebuild no longer error and are NOT excluded — remove them from dependencies (they are deprecated) or add them to the list.
  • Remove squirrelWindows.customSquirrelVendorDir — the option is deleted; supply a custom Squirrel bundle via toolsets.squirrel (a ToolsetCustom object) instead (note the different bundle layout).
  • Migrate any custom NSIS-binary and/or custom NSIS-resources to a toolsets.nsis bundle —Potentially relevant for builds reliant on NSIS (nsisWeb, portable, nsis). The .customNsisBinary and .customNsisResources config properties have been removed in favor of a new NSIS-bundle configured via toolsets.nsis. The new toolset consolidates the removed properties and provides both the NSIS binary and resources. Configuring the removed properties fails the build. customNsisBinary.debugLogging is now nsis.installerDebugLogging (moved by migrate-schema); it needs a log-enabled NSIS (NSIS_CONFIG_LOG=yes), which the default toolset (nsis@2.0.4) provides by downloading its log-enabled bundle; with a custom toolsets.nsis bundle, that bundle must be log-enabled.
  • RPM builds: the rpm target now uses the rpmbuild bundled in toolsets.archive on Linux x64/arm64 and macOS arm64, so host rpm macros (~/.rpmmacros, /etc/rpm) no longer apply; Intel macOS and 32-bit Linux still need rpmbuild installed.
  • Wine on macOS: toolsets.wine now defaults to the host install — a macOS host that builds Windows targets needs Wine installed (brew install --cask wine-stable).
  • macOS entitlements: the bundled default now grants only allow-jit — if your app loads native modules, frameworks, or plugins signed by another Team ID (or unsigned), add disable-library-validation (and allow-unsigned-executable-memory if needed) back in build/entitlements.mac.plist.
  • Missing dependencies: a production dependency that cannot be resolved now fails the build — fix the install or set allowMissingDependencies.
  • Native binaries: a .node addon built for another platform/arch now fails the build — rebuild it for the target, or set nativeModules.verifyNativeBinaries to "warn"/false.
  • macOS ASAR integrity digest: with Electron 41+, the Electron Framework is patched and signed again ad hoc after afterPack — set mac.asarIntegrityDigest: false if you sign the app yourself in afterPack, change app.asar / Info.plist after it, or merge separately built x64 and arm64 apps with @electron/universal yourself.
  • extraFiles / extraResources: a to that is absolute or escapes the output dir now throws.
  • Windows publisherName: is validated against the signing certificate — update win.sign.publisherName after a certificate rotation. A custom win.sign.sign hook (even with a certificate configured), or a certificate without a CN, now needs win.sign.publisherName for builds that write app-update.yml (nsis / nsis-web / electronUpdaterAware appx with a publish config, including one inferred from a GitHub repository); set win.verifyUpdateCodeSignature: false instead only if your updates are not Authenticode-signed or you don't use electron-updater.
  • Windows publisherName DN: every entry must be a distinguished name — a bare name now fails the build (e.g. "My Company" → "CN=My Company, O=My Company, C=US"); electron-updater 7 never matches one. Without publisherName, CN=<common name> of the certificate is written to app-update.yml.
  • Windows publisherName missing: a missing publisherName fails update verification — a build that writes app-update.yml with win.sign: false / null, without a certificate, or with win.sign.publisherName: null now fails, and electron-updater 7 rejects updates whose app-update.yml has no publisherName. Sign the build, set win.sign.publisherName (e.g. when signing outside electron-builder), or set win.verifyUpdateCodeSignature: false, the only opt-out.
  • Windows update verification: fails closed — an NSIS update PowerShell cannot verify is rejected instead of installed with a warning. If PowerShell may be blocked on your users' machines (AppLocker / WDAC), assign a native verifyUpdateFileAuthenticodeSignature in your first electron-updater 7 release: afterwards such installs can no longer receive the release that would add it.
  • NSIS update installer version: must carry the update's version — an update whose latest.yml signature is not verified is rejected (ERR_UPDATER_INSTALLER_VERSION_MISMATCH) when its installer's ProductVersion is not exactly the version of latest.yml. If you change an installer's version resource after the build or write latest.yml yourself, keep the two equal, or sign update manifests.
  • nsis-web update runs: need a package file — a web installer started with --updated but without --package-file aborts (exit code 2). If you write the latest.yml of an nsis-web release yourself, list its packages.
  • Linux updates without polkit: gksudo, kdesudo and beesu refuse unsafe installer paths — keep the deb/rpm/pacman artifactName and updaterCacheDirName to the allowed characters; else the update fails with ERR_UPDATER_UNSAFE_INSTALLER_PATH where pkexec is missing.
  • NSIS scripts: rename a customInstallmode macro to the documented customInstallMode.
  • Linux launcher: .desktop Exec now runs a *-launcher script and executableArgs field codes are literal — update custom .desktop / AppArmor / MIME tooling and move %F/%U to linux.desktop.entry.Exec. The flatpak target keeps its electron-wrapper entrypoint.
  • Flatpak: flatpak 1.12.4+ and flatpak-builder 1.2.2+ are required — the stock packages of Ubuntu 22.04, Debian 12 and newer meet this; update older tools on machines and images that build the flatpak target (the electronuserland/builder images with a date tag newer than -05.26 include them, those up to -05.26 none), and replace DEBUG=@malept/flatpak-bundler with DEBUG=electron-builder. To build in an unprivileged CI container, see Building in unprivileged containers.
  • Flatpak runtime: flatpak.runtimeVersion and flatpak.baseVersion now default to 26.08 (was 20.08, which is end-of-life) — a build that sets neither is built for the 26.08 runtime, and the build machine installs the 26.08 runtime, SDK and base app if they are missing (about 3.2 GB). Install them in images that held the 20.08 ones, or set both options to "20.08" to keep the previous runtime.
  • Flatpak permissions: the default flatpak.finishArgs no longer include --filesystem=home — only for builds without finishArgs: the app can reach the Downloads folder, its own data under ~/.var/app and the files the user picks in a dialog. If it opens other paths on its own (recent files, ~/Documents, dotfiles, ~/.pki/nssdb certificates), set finishArgs to the v26 list or add narrower grants such as --filesystem=xdg-documents.
  • Flatpak notifications: the default flatpak.finishArgs leave out --talk-name=org.freedesktop.Notifications on base app 23.08 and later, and with any other base — only for builds without finishArgs: notifications go through the notification portal, so they no longer appear on desktops without a portal backend for notifications (for example sway with only xdg-desktop-portal-wlr). If your users run such desktops, add the talk-name to finishArgs; a user can also run flatpak override --user --talk-name=org.freedesktop.Notifications <id>.
  • Update channels: suffixed channels (e.g. beta-arm64) now expand to lower channels with generateUpdatesFilesForAllChannels — set it to false to keep one file per suffixed channel.
  • electron-updater API: quitAndInstall takes an options object, autoInstallOnAppQuit → autoInstallEvent, and downloadUpdate() resolves with { updateFile, packageFile } — update app code.
  • TypeScript imports: renamed type exports (ElectronDownloadOptions → ElectronGetOptions, …) have no compat aliases.
  • Plugin/custom-target authors: replace packager.info.X and platformSpecificBuildOptions with the new pass-through getters.

Step 4: Custom NSIS Migration Guide​

If you do do not use either .customNsisBinary or .customNsisResources configurations on nsis nsis-web or portable in your <=v26 config there are no actions required and you can skip this step.

To migrate from .customNsisBinary/.customNsisResources to a new custom unified toolsets.nsis bundle requires manual steps.

A brief overview of this breaking change is good context before you start this migration. The NSIS Toolset Bundle docs may also be useful.

If you previously used .customNsisBinary in v26 or prior:​

  • Download & extract a copy of the new default NSIS Toolset Bundle from electron-builder-binaries as well as the archive you provided via .customNsisBinary.
  • Depending on what OS(es) your .customNsisBinary was built to support, you may have any subset of these three binaries that need to be copied over.
    • a. /Bin/makensis.exe
    • b. /linux/makensis
    • c. /mac/makensis
  • The NSIS Toolset Bundle you download is a valid toolsets.nsis bundle and provides easy locations you can drop any makensis binaries you into.
    • a. /windows/ ← Copy /Bin/makensis.exe From your .customNsisBinary archive to this path to migrate
    • b. /mac/x64 ← Copy /mac/makensis from a .customNsisBinary archive to this path to migrate
    • c. /mac/arm64
    • d. /linux/x64 ← Copy /linux/makensis from a .customNsisBinary archive to this path to migrate
    • e. /linux/arm64
  • When copying your custom binaries across you should overwrite the makensis executables already present in the new-bundle.
  • (optional) - As you can see, the new toolset.nsis bundle now provides native makensis binaries for newly supported targets like Mac (arm64) & Linux (arm64). You're welcome to provide binaries for as many (or as few) Operating-System/Architecture targets as you want in your custom toolset. You only need to provide a makensis/makensis.exe executable for the OS & arch combos you intend to run your builds with.
  • (optional) - The new toolsets.nsis is more flexible than previous .customNsisBinary/.customNsisResources in that the layout is customizable. The following files hook incoming makensis executions. This shim-script-layer opens up a path for custom dynamic logic to adjust binary/resources conditionally and on the fly.
    • a. /makensis ← Bash script, routes incoming makensis execution requests for macOS/Linux builds
    • b. /makensis.cmd ← Cmd script, routes incoming makensis execution requests for Windows builds running via Command Prompt
    • c. /makensis.ps1 ← PowerShell script, may be used in the future by electron-builder to route incoming windows builds
  • Include your newly created bundle in your electron builder config via toolsets.nsis by either:
    • a. Providing a file://<path-to-your-uncompressed-nsis-toolset-bundle-folder> as the toolsets.nsis.url.
    • b. Similar to how .customNsisBinary/.customNsisResources worked - host the bundle as a .7z file remotely. Provide the remote url as the toolsets.nsis.url & and provide the hash of the archive (either sha256-hex or sha512-base64) to the toolsets.nsis.checksum property.

If you previously used .customNsisResources in v26 or prior:​

  • Download & extract a copy of the new default NSIS Toolset Bundle from electron-builder-binaries as well as the archive you provided via .customNsisResources.

  • For the .customNsisResources, all 3rd party resource .dlls were located as such:

    • a. /plugins/x86-ansi/<plugin(s).dll>
    • b. /plugins/x86-ansi/<plugin(s).dll>
    • c. plugins/<Target>/<plugin(s)>.dll
  • The NSIS Toolset Bundle you download is a valid toolsets.nsis bundle and provides an easy locations you can drop in your resources. The root NSISDIR (NSIS Resources Directory) is now /windows/. The move of just resources is pretty straightforward:

    • a. /windows/Plugins/x86-ansi/<plugin(s).dll>
    • b. /windows/Plugins/x86-ansi/<plugin(s).dll>
    • c. plugins/<Target>/<plugin(s)>.dll
  • When copying your custom resources across you should overwrite the makensis executables already present in the new-bundle.

  • The complete common NSIS resources pulled by makensis binary runtime are /Stubs, /Include, /Contrib, /Plugins. Nothing outside of /plugins was previously supported by .customNsisResources. With the new NSIS toolset, if you have any of these resources then they can go here:

    • a. /windows/Plugins/
    • b. /windows/Include/
    • c. /windows/Contrib/
    • d. /windows/Stubs/
    • e. /windows/ ← Root NSISDIR (Nsis Resources Dir) by default
  • (optional) - The new toolsets.nsis is more flexible than previous .customNsisBinary/.customNsisResources in that the layout is customizable. The following files configure NSISDIR (NSIS Resource Directory). This shim-script-layer opens up a path to dynamically control NSISDIR on the fly.

    • a. /makensis ← Bash script, routes incoming makensis execution requests for macOS/Linux builds
    • b. /makensis.cmd ← Cmd script, routes incoming makensis execution requests for Windows builds running via Command Prompt
    • c. /makensis.ps1 ← PowerShell script, routes incoming makensis execution requests for Windows builds running via Powershell
  • Include your newly created bundle in your electron builder config via toolsets.nsis by either:

    • a. Providing a file://<path-to-your-uncompressed-nsis-toolset-bundle-folder> as the toolsets.nsis.url.
    • b. Similar to how .customNsisBinary/.customNsisResources worked - host the bundle as a .7z file remotely. Provide the remote url as the toolsets.nsis.url & and provide the hash of the archive (either sha256-hex or sha512-base64) to the toolsets.nsis.checksum property.
  • The toolsets.nsis bundle must carry elevate.exe at the bundle's root directory You can grab a copy one from the root of Electron Builder's default NSIS Toolset Bundle provided in electron-builder-binaries. It is used for privledge-control features by the UAC nsis plugin.

  • For more information/guidance you can checkout the toolsets.nsis documentation

Summary checklist​

Run electron-builder migrate-schema first — it handles the items marked ✓ automatically.

Runtime and CI

  • Node.js runtime updated to >=22.12.0
  • CI node-version updated to '22'
  • "engines" field in package.json updated (if declared)

Build config — auto-migrated by migrate-schema

  • ✓ electronCompile removed (if present)
  • ✓ disableDefaultIgnoredFiles removed (if present; re-include specific files via a fileOptions.files glob such as **/*.obj)
  • ✓ framework, nodeVersion, launchUiVersion removed (if present)
  • ✓ npmSkipBuildFromSource → nativeModules.buildDependenciesFromSource (if present)
  • ✓ buildDependenciesFromSource, nodeGypRebuild, npmRebuild moved into nativeModules; nativeRebuilder → rebuildMode
  • ✓ Legacy asar keys + asarUnpack → asar.unpack (platform-level too); disableSanityCheckAsar → asar.disableSanityCheck; disableAsarIntegrity → asar.disableIntegrity; asar: true removed
  • ✓ macOS signing fields → mac.sign.*; signIgnore → sign.ignore (also mas/masDev)
  • ✓ mac.universal fields → mac.universal.*
  • ✓ files / extraResources / extraFiles → fileOptions.* (root and mac/mas/masDev/win/linux)
  • ✓ includePdb → fileOptions.excludedExts (if present; true → ["default", "!pdb"], false → ["default"], the v27 default written out so that it keeps overriding an includePdb: true of another config layer; replace an includePdb passed programmatically or with -c by hand, e.g. -c.includePdb=false → -c.fileOptions.excludedExts=default, -c.includePdb=true → -c.fileOptions.excludedExts=default -c.fileOptions.excludedExts=!pdb (in an interactive bash or zsh, single-quote the second flag: '-c.fileOptions.excludedExts=!pdb'); a list of removals only, such as ["!pdb"], is rejected because it would exclude no extension at all: write ["default", "!pdb"])
  • ✓ electronDownload → electronGet (verify dropped cache/customDir/customFilename/strictSSL/platform/arch/version/force)
  • ✓ appImage.systemIntegration removed (if present)
  • ✓ linux.syncDesktopName removed (if present; always synced in v27 — set desktopName if you had it false)
  • ✓ GithubOptions.vPrefixedTagName → tagNamePrefix (if present)
  • ✓ win.azureSignOptions / win.signtoolOptions → win.sign; win.signExecutable / win.signAndEditExecutable handled
  • ✓ snap restructured to snapcraft (verify the assumed base if none was set)
  • ✓ helper-bundle-id → mac.helperBundleId; squirrelWindows.noMsi → msi; root-level directories → build.directories
  • ✓ toolsets.*: null removed; toolsets.appimage: "1.0.2" → "1.0.3" and "1.2.0" → "1.2.1"; nativeRebuilder: "legacy" dropped

Runtime defaults & auto-update

  • DMG filesystem default is now APFS — set dmg.filesystem: "HFS+" only for pre-10.13 macOS compatibility
  • macOS default entitlements now grant only allow-jit — add allow-unsigned-executable-memory / disable-library-validation back in build/entitlements.mac.plist (and .inherit.plist for nested binaries) only if your app loads foreign-signed or unsigned binaries; MAS builds without build/entitlements.mas.plist now get osx-sign's sandboxed default
  • electron-updater disableWebInstaller defaults to true — web-installer updates are rejected unless it is false; v27+ nsis-web installs opt in automatically, set disableWebInstaller: false for older web-installer installs or when switching from nsis to nsis-web; the nsis-web installer verifies its app package (nsisWeb.allowUnverifiedAppPackage opts out)
  • A code-signed Windows build that writes app-update.yml needs a publisher name — set win.sign.publisherName for a custom win.sign.sign hook or a certificate without a CN, or win.verifyUpdateCodeSignature: false if your updates are not Authenticode-signed
  • Windows update signature verification fails closed — where PowerShell may be blocked, ship a native verifyUpdateFileAuthenticodeSignature in your first electron-updater 7 release
  • NSIS update installers must carry the update's version — without a signed latest.yml, the installer's ProductVersion must equal its version exactly (ERR_UPDATER_INSTALLER_VERSION_MISMATCH)
  • An nsis-web installer started as an update needs a package file — list the packages of a hand-written nsis-web latest.yml
  • Linux: gksudo, kdesudo and beesu refuse unsafe installer paths — where pkexec is missing, keep the deb/rpm/pacman artifactName and updaterCacheDirName to letters, digits and ._/+,:=@%-, else the update fails with ERR_UPDATER_UNSAFE_INSTALLER_PATH; installing polkit avoids it
  • NSIS per-machine builds set isAdminRightsRequired — their updates are started with elevate.exe and not installed automatically at launch; with autoInstallEvent: "onNextLaunch", call installPendingUpdateIfAvailable()
  • Update credentials stay on the feed's origin — requestHeaders / addAuthHeader credentials and the feed URL's query are not sent to downloads on another origin
  • The app chooses the headers sent to another origin — set autoUpdater.crossOriginHeaders (e.g. () => []) before the first check, and before ready for an install at launch
  • Update requests require https — an http feed, download or redirect to a host that is not loopback fails with ERR_UPDATER_INSECURE_FEED; autoUpdater.allowInsecureFeed = !app.isPackaged opts out in dev runs
  • Update manifests whose YAML aliases expand too far are rejected — write latest*.yml without YAML aliases if a tool of your own rewrites it; Bitbucket and Keygen report an unparsable manifest with ERR_UPDATER_INVALID_UPDATE_INFO
  • latest*.yml drops legacy top-level path/sha512; default electronUpdaterCompatibility is now >=2.16 — read files[] instead; pin a legacy-inclusive range only for legacy embedded updaters
  • Production dependencies that electron-builder provides or that your bundler inlines (electron/electron-builder/react/…) are excluded from the copied node_modules instead of erroring; ALLOW_ELECTRON_BUILDER_AS_PRODUCTION_DEPENDENCY removed and electron-prebuilt/electron-rebuild no longer guarded — tune via ignoredProductionDependencies
  • Building Windows targets on macOS uses the host Wine (toolsets.wine defaults to "system") — install Wine on macOS build machines
  • Flatpak runtimeVersion / baseVersion default to 26.08 (was 20.08) — set both to "20.08" only to keep the previous runtime
  • Flatpak default finishArgs grant --filesystem=xdg-download instead of --filesystem=home — set flatpak.finishArgs if the app needs home access
  • Flatpak default finishArgs leave out --talk-name=org.freedesktop.Notifications on base app 23.08 and later, and with any other base — add it to flatpak.finishArgs for desktops without a notification portal backend

Manual steps — see Step 3 & Step 4 above.

Plugin and custom-target authors — see the programmatic API changes.


Full breaking-changes reference​

Every change above is documented in detail — with rationale (design notes) and before/after for each — on the v27 Breaking Changes page.