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" }

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 generic publish configuration whose url has a query string, and a mac/mas/masDev section that names no entitlements file. 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:

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"; 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
  • 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
  • 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.