electron-userland/electron-builder electron-builder@27.0.0-alpha.11

on GitHub

Major Changes

• Feat!: nest files, extraResources and extraFiles under fileOptions #10319 8f55928 — electron-builder, app-builder-lib, builder-util-runtime

  The three file-copy lists live in a fileOptions?: FilesBuildOptions | null property at the configuration root and in every platform section (mac, mas, masDev, win, linux), the same way directories groups the build directories: fileOptions.files, mac.fileOptions.extraResources, and so on. PlatformSpecificBuildOptions does not extend FilesBuildOptions, and the TypeScript types and the JSON schema only have fileOptions.

  Flat files / extraResources / extraFiles keys in a config file, an extends parent, a -c.files=… override or the config object passed to build() are applied as their fileOptions counterparts before the configuration is validated, logging one warning per process that names the keys found and where they belong. When a flat key and its fileOptions counterpart are set on the same object, fileOptions wins and the build warns about the conflict. A CLI override or a parent config's flat key is merged with fileOptions. A fileOptions that is not an object (for example a list of globs written directly under it) fails the build with a message showing the nested form.

  Code that reads files, extraResources or extraFiles from the loaded configuration (for example a hook reading context.packager.config.files, or buildResult.configuration.extraResources) gets the fileOptions value, with a warning per key: the loaded configuration and its platform sections forward these reads through non-enumerable properties, which stay out of the effective config, JSON.stringify and Object.keys. Assigning them throws a configuration error naming the fileOptions property to set instead.

  deepAssign (builder-util-runtime) copies only enumerable own properties, so the forwarding properties are never copied into merged options.

  electron-builder migrate-schema (static and JS/TS configs) moves flat keys under fileOptions at the root and per platform. A flat key also set under fileOptions is removed with a warning, since the build ignores it.

  See https://www.electron.build/docs/migration/v27-breaking-changes#file-options-fileoptions

• Fix: confine linked files to the workspace and package-manager store by real path; opt in to external links with fileOptions.allowExternalLinks. A file of the app (packed into app.asar or copied with asar: false) that is a symlink, or is reached through one, is packaged only when its real path is inside the workspace root, the project or app directory, or the package-manager store (pnpm storeDir/virtualStoreDir from node_modules/.modules.yaml). Any other one, such as an npm link or a file: dependency outside the workspace, fails with InvalidConfigurationError (code ERR_ELECTRON_BUILDER_FILE_OUTSIDE_WORKSPACE), which names the file, its real path and the fileOptions.allowExternalLinks entry that allows it (true, or a list of directories, relative to the project directory or absolute, that linked files may resolve into; at the top level or per platform; default false, with a one-time warning when it allows a link). See https://www.electron.build/docs/contents#linked-files-must-resolve-inside-the-workspace #10321 08e8044 — app-builder-lib

• Fix: confine copies to the app output directory by real path, so that a symlink among copied files (app directory, extraResources/extraFiles/extraDistFiles sources, node_modules) cannot make electron-builder write or package files elsewhere on the build machine; opt in to external links with fileOptions.allowExternalLinks. copyDir (extraResources/extraFiles) and the asar: false app copy refuse a destination whose directory resolves outside the app output directory, replace (never follow) a symlink at a destination file, and recreate a symlink only when it stays inside the output (or, for extraResources/extraFiles, leads into the workspace or the package-manager store, with a one-time warning). The fixed-name files written after the copies (app-update.yml, package-type, apparmor-profile, NSIS elevate.exe, the snap command.sh, Squirrel.exe and the Squirrel execution stub) replace a symlink at their name instead of writing through it. Windows zip/7z archives, the NSIS app package, AppX/MSIX and Squirrel.Windows packages, which store what a symlink points to, refuse a symlink that leaves the app. An intended symlink of this kind is allowed by the fileOptions.allowExternalLinks build option (true, or a list of directories its real target may be in; at the top level or per platform, a platform's value replacing the top-level one), with a one-time warning; a write through a symlink is always refused. Errors are InvalidConfigurationError with code ERR_ELECTRON_BUILDER_PATH_OUTSIDE_ROOT, suggest the fileOptions.allowExternalLinks entry and link to https://www.electron.build/docs/contents#symlinks-that-leave-the-app-are-refused. New builder-util helpers: assertWritableWithin, prepareFixedNameWrite, WriteContainment, resolvePhysicalPath, findEscapingSymlinks, assertNoSymlinkLeaves, ExternalLinkPolicy. #10321 08e8044 — app-builder-lib, builder-util, electron-builder-squirrel-windows

• Feat(flatpak): build bundles with flatpak and flatpak-builder directly, without @malept/flatpak-bundler, and build in unprivileged containers #10316 3f1d50b — app-builder-lib

  The flatpak target now runs flatpak and flatpak-builder itself, and the @malept/flatpak-bundler dependency is removed. A failed command prints the tool's output in the build error, and five known failures (Failure spawning rofiles-fuse, a bwrap: failure in flatpak build-export, No remote refs found, Command 'electron-wrapper' not found when rofiles-fuse cannot mount the app directory, and execvp appstream-compose when a flatpak-builder older than 1.4 composes AppStream metadata with the freedesktop SDK 24.08 or newer) log how to fix them first. A build with flatpak.modules warns once when flatpak-builder is older than 1.4.4, which the 24.08 and newer SDKs recommend for meson and cmake modules. The scratch directory is removed when the build ends.

  New options:

  • flatpak.additionalArgs passes extra arguments to the tools, by tool: flatpakBuilder, buildExport and buildBundle. With { flatpakBuilder: ["--disable-rofiles-fuse"], buildExport: ["--disable-sandbox"] } the target builds in CI containers that have neither FUSE nor user namespaces (#10306).
  • flatpak.installOrUpdateRefs, "all" (the default) or a list of "runtime", "sdk" and "base": the refs that are left out are used as installed, without a flatpak install or flatpak update, and a missing one fails the build before anything is downloaded. [] builds with the refs of an image or an offline machine, and where the build user cannot update the base app (based on the options proposed in #10313).

  BREAKING CHANGE: flatpak >= 1.12.4 and flatpak-builder >= 1.2.2 are required, and checked before a runtime is installed. The stock packages of Ubuntu 22.04, Debian 12, RHEL 8 and 9 and newer releases meet this; v26 accepted older tools. DEBUG=@malept/flatpak-bundler no longer has any effect, and a flatpak build warns once when DEBUG still names it: use DEBUG=electron-builder to log every command.

  BREAKING CHANGE: flatpak.runtimeVersion and flatpak.baseVersion default to 26.08 instead of 20.08, which Flathub reports as 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). A build that leaves either option unset warns once, naming electron-builder v27 and the migration guide. Set both to "20.08" to keep the previous ones.

  BREAKING CHANGE: the default flatpak.finishArgs grant --filesystem=xdg-download instead of --filesystem=home: with read/write access to the home directory, code running in the app could write ~/.config/autostart or ~/.bashrc and so run outside the sandbox at the next login. App data under ~/.var/app and files picked in a dialog are not affected; paths the app opens on its own outside Downloads are. They also leave out --talk-name=org.freedesktop.Notifications unless the base is org.electronjs.Electron2.BaseApp older than 23.08, whose libnotify predates the notification portal; on desktops without a portal backend for notifications, notifications no longer appear. Builds that set flatpak.finishArgs are not affected, and a build that uses the defaults warns once, naming electron-builder v27 and the migration guide. To keep the v26 permissions, set finishArgs to the v26 list from the migration guide.

  BREAKING CHANGE: a flatpak.files destination or a flatpak.symlinks link that leaves the app prefix with .. fails the build with an InvalidConfigurationError, before anything is installed. It was written outside the app in the build directory, for example over the app's metadata. The pairs of flatpak.files are copied one after another, and a directory can no longer be copied onto a symlink to a directory: v26 copied through the link, and the build now fails with Cannot overwrite non-directory with directory (ERR_FS_CP_DIR_TO_NON_DIR). Symlinks inside a copied directory are kept as they are. The errors of the tool-version check and of the app-prefix check say that they are new in electron-builder v27 and link the migration guide.

Minor Changes

• Feat(app-builder-lib): warn at build start when a process.env variable removed in v26 → v27 is still set #10293 d2c979b — app-builder-lib

  • Added warnOnRemovedEnvVars() (registry in app-builder-lib/src/util/removedEnvVars.ts), invoked once per build from the Packager constructor so both the CLI and programmatic build() API surface the same guidance. When a removed variable is still present in the environment it is otherwise silently ignored — this logs a one-time deprecation warning naming the variable and its replacement.
  • Covers the removed toolset-path overrides (APPIMAGE_TOOLS_PATH, MKSQUASHFS_PATH, LINUX_TOOLS_MAC_PATH, CUSTOM_FPM_PATH, ELECTRON_BUILDER_NSIS_DIR, ELECTRON_BUILDER_NSIS_RESOURCES_DIR, CUSTOM_NSIS_RESOURCES, ELECTRON_BUILDER_WINE_TOOLSET_DIR, ELECTRON_BUILDER_7ZIP_PATH, ELECTRON_BUILDER_ICONS_TOOLSET_DIR, ELECTRON_BUILDER_OSSL_SIGNCODE_PATH, ELECTRON_BUILDER_RCEDIT_PATH, ELECTRON_BUILDER_WINDOWS_KITS_PATH, SIGNTOOL_PATH) → toolsets.* / win.sign; the USE_SYSTEM_* toggles; ELECTRON_BUILDER_BINARIES_ALLOW_HTTP → ELECTRON_BUILDER_DANGEROUSLY_ALLOW_HTTP; CI_BUILD_TAG → CI_COMMIT_TAG; and ALLOW_ELECTRON_BUILDER_AS_PRODUCTION_DEPENDENCY → ignoredProductionDependencies.
  • Internal/test-only variables (JEST_WORKER_ID, TEST_SET_BABEL_PRESET) and npm_lifecycle_event (set by npm for every script) are intentionally excluded from the runtime scan.
  • Migration docs: filled the previously undocumented removed vars in the v27 breaking-changes catalogue (the toolset-path family plus MKSQUASHFS_PATH), added a "Replace with" column, and documented the ELECTRON_BUILDER_BINARIES_ALLOW_HTTP rename and the removed npm run release implicit-publish behavior.

• Feat(builder-util): log.limit({ key, max, scope }) / log.once(key, scope) emit a keyed message at most N times (per process, or per scope object), replacing hand-rolled "already warned" flags; electron-updater counts once-per-updater warnings internally without changing the injectable Logger interface. Both share one limiter (wrap() on any { info, warn, error, debug? } logger, including console), and its LogLevel, LogLimitOptions, LoggerLike and LimitedLogger types are now exported from builder-util-runtime (builder-util re-exports them) #10302 5cbbc8d — electron-builder, app-builder-lib, builder-util, builder-util-runtime

• Fix(asar): asar.ordering is now honored — the documented option was typed but never applied to the archive electron-builder packs (it packs through @electron/asar's stream API, which takes no ordering option). Listed files are packed first, in the order of the file (same line syntax as @electron/asar: optional leading / or <count>: prefix, blank lines ignored), directories keep their positions, everything else follows in its original order; coverage is logged. #10310 8eff005 — app-builder-lib

• Feat(snap): "default" in snapcraft.core24.plugs now merges the remaining entries into the full default plug set (including browser-support and, without the gnome extension, the content-snap plugs), deduplicated by name, with descriptor objects overriding a default plug's attributes #10294 efec238 — app-builder-lib

• Feat(flatpak): warn about --no-sandbox and the flatpak id, and fix the wrapper, useWaylandFlags, MIME types and failed builds #10316 3f1d50b — app-builder-lib

  • Warns once per build when --no-sandbox reaches the flatpak's electron-wrapper, naming linux.executableArgs and/or flatpak.executableArgs as its source: inside flatpak, Chromium's sandbox works through zypak, and the flag gives renderer processes every permission of the app. The flag is kept. linux.executableArgs are merged into the flatpak options, and an empty flatpak.executableArgs adds nothing: --no-sandbox for the AppImage alone belongs in appImage.executableArgs, and flatpak.executableArgs: null leaves all of linux.executableArgs out of the flatpak.
  • Warns once per build when the flatpak id is derived from the package name (neither linux.appId nor appId is set: the id names the app's ~/.var/app/<id> data directory, and another vendor's bundle with the same com.electron.<name> id installs over the app), and when desktopName is set but is not <flatpak id>.desktop (the bundle's desktop entry is named after the id, and Electron names the app's windows after desktopName, so desktops cannot match the two).
  • The electron-wrapper script replaces itself with the app (exec) instead of staying as its parent shell, and tests the session with the POSIX =: the == failed with "unexpected operator" where /bin/sh is dash, and dropped the Wayland flags.
  • flatpak.useWaylandFlags picks its flags by Electron version: none from Electron 38, which chooses Wayland by itself in a Wayland session (the build logs that the option has no effect), --ozone-platform=wayland from Electron 16, and --enable-features=UseOzonePlatform --ozone-platform=wayland before that or for an unknown version. From Electron 16 the wrapper no longer adds a second --enable-features, which could replace one in executableArgs; a build with Electron 16 to 37 warns once about the change, naming electron-builder v27 and the migration guide.
  • An invalid flatpak id (fewer than three elements, an empty element or one starting with a digit, more than 255 characters), such as com.myapp or com.electron.3d_viewer from a package named 3d-viewer, fails the build before the runtime, SDK and base app are installed, with an InvalidConfigurationError naming the rule. It failed in flatpak-builder, after those were installed (about 3.2 GB for the default version).
  • The __flatpak-<arch> stage directory is removed from the output directory when preparing it fails, for example on an invalid desktop entry or a missing license file.
  • The MIME types of fileAssociations (every mimeType that is set) are declared in the bundle's share/mime/packages/<id>.xml, which flatpak exports, as the AppImage and deb/rpm targets do: the desktop entry listed the types, but nothing defined a custom one. Set mimeType only for a type of your own: each is declared with the description <productName> document, which for a standard type such as text/markdown can change how the desktop describes every such file. List standard types in linux.mimeTypes, which only adds them to the desktop entry.

• Feat(asar): asar.contentAlignment — align the start of every packed file's content inside app.asar to a multiple of N bytes (zero padding between files; order, sizes and per-file integrity unchanged). Meant for differential updates with nsis.differentialPackage: "store-asar": the asar header stores absolute content offsets, so without alignment a change that grows a file by one byte shifts every later offset and most of the header is re-downloaded; with 512 a small length-changing edit measured 414 KB → 139 KB of differential download for 2.2 % more asar size. Off by default. #10311 a4ff5db — app-builder-lib

Patch Changes

• Chore(deps): update @electron/___ dependencies to latest #10244 a49daae — app-builder-lib

• Fix: encode GitLab publisher package path segments #10140 4b6e63f — electron-publish

• Fix: escape Squirrel project URLs in nuspec XML #10141 09a2f30 — electron-builder-squirrel-windows

• Fix: stop retry backoff immediately when cancelled #10126 68aa2ff — builder-util-runtime

• Fix(appimage): resolve a toolsets.appimage version pin to exactly that release instead of letting any pin other than "1.0.3" float to the newest bundle, and reject unknown versions with an InvalidConfigurationError rather than downloading without a checksum #10291 86298ab — app-builder-lib

• Fix(snap): pack legacy-base (core18/core20/core22) template snaps with the mksquashfs from toolsets.appimage instead of the hardwired legacy "0.0.0" bundle, whose mksquashfs supports only gzip/xz, so compression: "lzo" (and linux.compression: "store", which maps to lzo) builds again (#7013); a toolsets.appimage: "0.0.0" pin combined with lzo now fails early with an InvalidConfigurationError instead of inside mksquashfs #10291 86298ab — app-builder-lib

• Fix(nsis): the installer copies itself into %LOCALAPPDATA%\<app>-updater only when the app has an app-update.yml. Before, every install kept that copy, which only electron-updater reads (as the base for a differential download), so apps without an update configuration carried a second copy of their installer, and the uninstaller left it behind. After, those apps get no copy; apps with an update configuration keep it as before. #10261 0df65dc — app-builder-lib

• Fix(nsis): log once when the installer skips keeping its copy for electron-updater's differential download cache because resources/app-update.yml was not found #10298 38fe001 — app-builder-lib

• Fix(nsis): point the removed customNsisBinary / customNsisResources build error and migrate-schema warning at the custom NSIS migration guide and the toolsets.nsis bundle docs, and fix their stale breaking-changes anchor #10286 7e42d2f — app-builder-lib

• Fix: retry an Electron/toolset download that times out instead of failing the build. Before, a silent connection ended in undici's 300s headers/body timeout, which was not treated as retryable, and the 10 minute cap on a download was one AbortSignal.timeout() shared by all attempts, so no attempt could follow it. After, each attempt gets its own 10 minute cap, and an attempt that hits it or undici's timeouts is retried once, with a warning in the log. #10269 e7d9cad — app-builder-lib

• Fix(docs): repair broken links and anchors across the docs site and JSDoc, and export the SnapOptions24, SnapOptionsLegacy, SnapOptionsCustom and RemoteBuildOptions types from app-builder-lib so their API reference pages are generated #10305 2fdbcae — app-builder-lib, builder-util-runtime

• Refactor: once-only build and updater warnings use log.once / log.limit (and the updater's per-instance counter) instead of hand-rolled flags and sets; a concurrently resolved NSIS ProgID notice can no longer print twice #10303 6fe881e — app-builder-lib

• Fix: reject shell line-break characters #10131 8854be3 — builder-util

• Fix: honor uppercase http(s) proxy environment variables #10132 ea41d9a — builder-util

• Fix: reject aborted S3 upload responses #10145 80c9c3f — app-builder-lib, electron-publish

• Fix: enforce workspace path boundaries for asar #10135 ed43b10 — app-builder-lib

• Fix: accept forward slashes in isOutsidePath on Windows #10307 0dffd5b — app-builder-lib

• Fix: bump @electron/rebuild to 4.2.1 so cross-platform builds from one node_modules no longer reuse a native module built for another platform (#10031) #10308 067913d — app-builder-lib

• Fix(asar): a missing asar.ordering file now fails with a configuration error naming the paths tried and the v27 migration notes, builds that apply an ordering file warn once that the option is now honored, ordering lines with \ separators match on macOS and Linux, and lines naming a directory no longer count as missing in the coverage log #10320 866bb00 — app-builder-lib

• Fix: contain mapped app file destinations #10137 bb6b24c — app-builder-lib

• Fix(snap): core24 no longer requests browser-support with allow-sandbox by default (the Snap Store rejects it for non-vetted publishers); default core24 snaps now launch with --no-sandbox and omit chrome-sandbox, and an explicitly configured allow-sandbox logs a store-review warning #10294 efec238 — app-builder-lib

• Docs(blockmap): state the regions size/sha512 guarantee for file-output mode only #10325 d2af5d1 — app-builder-lib

• Fix(linux): validate .desktop entry keys and values before writing them, for every Linux target #10316 3f1d50b — app-builder-lib

  The desktop entry of every Linux target that writes one is checked before it is written, so a configuration can no longer produce a corrupt .desktop file. The build fails with an InvalidConfigurationError naming the group and the key for a value with \r or \n inside it (from linux.desktop.entry, desktopActions, linux.category, linux.mimeTypes, fileAssociations or protocols), whose second line would become a new key or group of the file; a key that GLib, which most desktops read the file with, rejects (empty, or with =, a line break, or brackets other than a trailing locale such as Name[de]), which makes it ignore the whole file; and a desktopActions name with [, ] or a control character. Write such a value on one line, with a newline in a string value as \n. Line breaks at the end of a value, as in a YAML block scalar, are dropped, and values are otherwise still written as given, so escapes such as \; keep working. Keys that the specification does not allow but desktop environments read, such as X_Foo, are kept.

• Fix(snap): stop deleting chrome-sandbox from the shared linux-unpacked dir when building a core18/core20/core22 template snap. The delete raced the other Linux targets, so a deb, rpm or AppImage built in the same run could ship without chrome-sandbox (no SUID sandbox fallback), and AppImage could fail with ENOENT. The snap still omits chrome-sandbox; the mksquashfs input list already filters it out. #10327 798adc4 — app-builder-lib

Full Changelog: https://github.com/electron-userland/electron-builder/compare/electron-builder@27.0.0-alpha.10...electron-builder@27.0.0-alpha.11