Skip to main content

Interface: CommonConfiguration

Configuration options shared across all platforms.

These properties apply regardless of the target platform and control general build behaviour such as the application identity, output paths, native dependency rebuilding, toolset versions, and platform-specific target sub-configurations.

Extended by​

Properties​

allowMissingDependencies?​

readonly optional allowMissingDependencies?: boolean | string[] | null

Whether production dependencies that cannot be resolved during node-module collection are allowed — i.e. whether the build should continue with a warning instead of failing.

During collection every production dependency must resolve to an installed package on disk. A dependency that does not resolve (cannot find path for dependency / dependency not found on disk) is not bundled, which typically breaks the packaged app at runtime with MODULE_NOT_FOUND.

  • false or null (default): the build fails after dependency collection completes, reporting the complete list of missing production dependencies at once.
  • string[]: the listed dependency names are allowed to be missing; any other missing production dependency still fails the build. Entries match the package name of the reported name@version entry (e.g. some-native-module, @scope/pkg), or an exact name@version string to allow only that resolved version to be missing.
  • true: missing production dependencies are only logged as warnings (the electron-builder ≤ 26 behavior).

Missing optional dependencies (declared in optionalDependencies, e.g. fsevents on Linux/Windows, or platform-specific packages) are always allowed and never fail the build.

Independent of ignoredProductionDependencies, which controls which dependencies are excluded from the copied node_modules; this option only controls validation of the collection result.

Default​

false

apk?​

readonly optional apk?: LinuxTargetSpecificOptions | null

Alpine Linux APK package options.

Produces an .apk archive installable via apk add --allow-untrusted ./package.apk.

appId?​

readonly optional appId?: string | null

The application identifier.

Used as CFBundleIdentifier on macOS and as the Application User Model ID on Windows (NSIS target only; Squirrel.Windows does not support custom Application User Model IDs).

It is strongly recommended to set an explicit, reverse-DNS-style identifier (e.g. "com.example.myapp") rather than relying on the generated default.

Default​

com.electron.${name}

appImage?​

readonly optional appImage?: AppImageOptions | null

AppImage options.

AppImage is a portable application format that bundles the app and its runtime dependencies into a single self-contained executable that runs on most Linux distributions without installation. The produced .AppImage file is executable after chmod +x.

See​

AppImageOptions

appx?​

readonly optional appx?: AppXOptions | null

Windows Store (MSIX/AppX) package options.

Produces a .appx or .msix package suitable for distribution through the Microsoft Store or side-loading.

See​

AppXOptions

buildNumber?​

readonly optional buildNumber?: string | null

The build number.

Maps to the --iteration flag for FPM-based Linux targets and is appended to the version string in CFBundleVersion (macOS) and FileVersion (Windows) when buildVersion is not set explicitly.

If not set, falls back to the first defined environment variable among: BUILD_NUMBER, TRAVIS_BUILD_NUMBER, APPVEYOR_BUILD_NUMBER, CIRCLE_BUILD_NUM, BUILD_BUILDNUMBER, CI_PIPELINE_IID.

buildVersion?​

readonly optional buildVersion?: string | null

The full build version string.

Maps to CFBundleVersion on macOS and the FileVersion metadata field on Windows. Defaults to the version field from package.json.

If buildVersion is not set but buildNumber is defined (or resolved from an environment variable), the effective build version becomes ${version}.${buildNumber}.

concurrency?​

readonly optional concurrency?: Concurrency | null

Configuration for experimental concurrent (multi-platform / multi-arch) builds.

When jobs > 1, electron-builder runs up to jobs platform builds in parallel. This is an experimental feature — use with caution and verify that your hook functions and build resources are safe to execute concurrently.

See​

Concurrency

readonly optional copyright?: string | null

The copyright string embedded in the built artifacts.

Appears in the Windows LegalCopyright version-info field and the macOS NSHumanReadableCopyright Info.plist key.

Default​

Copyright © ${year} ${author}

deb?​

readonly optional deb?: DebOptions | null

Debian package options.

Targets Debian, Ubuntu, and Debian-based distributions. Produces a .deb archive installable via dpkg -i or apt install ./package.deb.

See​

DebOptions

directories?​

readonly optional directories?: MetadataDirectories | null

Overrides for input/output directory paths used during the build.

See​

MetadataDirectories

dmg?​

readonly optional dmg?: DmgOptions | null

macOS DMG disk image options (background image, window position, icon layout, licence, etc.).

See​

DmgOptions

downloadAlternateFFmpeg?​

readonly optional downloadAlternateFFmpeg?: boolean

Whether to download the FFmpeg library variant from Electron's release assets and replace the default (proprietary codec) FFmpeg library before signing.

The alternate FFmpeg is compiled without proprietary codec support (H.264, AAC, etc.) and is required for distributing on certain platforms (e.g., Linux distributions that prohibit proprietary codecs). Enabling this swaps the bundled ffmpeg dynamic library before the app is signed.

electronFuses?​

readonly optional electronFuses?: FuseOptionsV1 | null

Options forwarded to @electron/fuses to flip Electron feature flags in the binary.

Fuses are compile-time-like flags baked into the Electron binary that cannot be changed at runtime. Flipping them is the approved mechanism for hardening Electron apps (e.g., disabling ELECTRON_RUN_AS_NODE, enabling ASAR integrity, etc.).

electron-builder flips fuses after packaging but before signing so that the final signature covers the modified binary.

See​

FuseOptionsV1

extraMetadata?​

readonly optional extraMetadata?: any

Additional properties to deep-merge into the app's package.json at build time.

Useful for injecting build-time metadata (e.g., a git commit hash or CI build URL) that should be readable at runtime via require('./package.json') or import.meta.url.

Example​

{ "extraMetadata": { "commitHash": "abc1234", "buildDate": "2025-01-01" } }

flatpak?​

readonly optional flatpak?: FlatpakOptions | null

Flatpak options.

Flatpak is a sandboxed application distribution format for Linux distributed via Flathub or self-hosted OSTree repositories.

See​

FlatpakOptions

forceCodeSigning?​

readonly optional forceCodeSigning?: boolean

Whether to throw an error and abort the build if the app could not be code-signed.

Set to true in release pipelines to catch missing or misconfigured signing credentials before producing unsigned artifacts. When false (the default), missing signing credentials produce a warning and the build continues unsigned.

Default​

false

freebsd?​

readonly optional freebsd?: LinuxTargetSpecificOptions | null

FreeBSD pkg package options.

Produces a .pkg archive for the FreeBSD package manager.

ignoredProductionDependencies?​

readonly optional ignoredProductionDependencies?: string[] | null

Names of production dependencies that are excluded from the copied node_modules, even if they are declared in the dependencies section of package.json.

electron-builder copies the resolved production dependency tree into the app. Some packages — notably electron — are already provided another way (the Electron runtime is embedded separately), so copying them would just duplicate what is already there. Such packages are excluded from the copy rather than rejected: they remain valid production dependencies for tooling purposes (e.g. SBOM, license, and vulnerability tracking) without being shipped twice.

Only dependencies declared by the app itself are eligible: a listed name and the transitive dependencies required only by it are dropped, while anything also required by another (kept) production dependency stays bundled. A matching name that appears solely as a transitive dependency of a kept package is never excluded. Note that a kept package which require()s an excluded name at runtime without declaring it (relying on hoisting) will fail with MODULE_NOT_FOUND — declare such a dependency properly or remove the name from this list.

Matching is by the dependency name as declared in package.json: an npm alias ("custom-electron": "npm:electron@^30.0.0") is matched by its alias key (custom-electron), never by the underlying package name.

Overriding this option replaces the default list, so include electron and electron-builder unless you intend to ship them. The most common reason to override is to add a dependency that a bundler (Vite, webpack, esbuild, …) already inlines into your app code: keep it in dependencies so SBOM/license tooling still sees it, and list it here so a duplicate copy is not packaged — e.g. ["electron", "electron-builder", "react", "react-dom"]. Removing a default name keeps that package in the copied node_modules. Setting the option to null (or omitting it) applies the default list; to disable exclusion entirely, set it to an empty array []. Each excluded package is logged once during packaging.

Default​

["electron", "electron-builder"]

includePdb?​

readonly optional includePdb?: boolean

Whether to include .pdb (Program Database) symbol files in the output.

PDB files enable Windows crash-dump analysis but significantly increase artifact size. Enable for internal builds where you want symbol information; disable for public distribution.

Default​

false

linux?​

readonly optional linux?: LinuxConfiguration | null

General Linux build options shared across all Linux targets (icon, category, desktop entry, executable name, etc.). Target-specific compression and packaging options live in the per-format interfaces (DebOptions, RpmOptions, PacmanOptions, etc.).

See​

LinuxConfiguration

mac?​

readonly optional mac?: MacConfiguration | null

macOS-specific build options (signing, entitlements, notarization, target categories, etc.).

See​

MacConfiguration

mas?​

readonly optional mas?: MasConfiguration | null

macOS App Store (MAS) submission options.

See​

MasConfiguration

masDev?​

readonly optional masDev?: MasConfiguration | null

macOS App Store development-signing options (mas-dev target). Used for local testing of MAS builds without submitting to the store.

See​

MasConfiguration

msi?​

readonly optional msi?: MsiOptions | null

WiX-based MSI installer options.

Produces a traditional .msi package built with the WiX Toolset. Best for enterprise deployments that require MSI-based installation policies.

See​

MsiOptions

msiWrapped?​

readonly optional msiWrapped?: MsiWrappedOptions | null

MSI-wrapped NSIS installer options.

Wraps the standard NSIS installer inside an MSI package so that it can be deployed via Group Policy or other MSI-only channels while preserving the NSIS installer UX.

See​

MsiWrappedOptions

msix?​

readonly optional msix?: MsixOptions | null

MSIX package options. MSIX is the modern successor to AppX with additional deployment features.

nativeModules?​

readonly optional nativeModules?: NativeModulesConfig | null

Configuration for native Node.js module installation and rebuilding.

Groups all options that control how electron-builder handles native modules — from forcing source builds during install through to the @electron/rebuild compilation mode.

See​

NativeModulesConfig

npmArgs?​

readonly optional npmArgs?: string | string[] | null

Additional command-line arguments appended to the package manager's install command when electron-builder installs app dependencies (i.e., when node_modules is missing and a fresh install is required).

These arguments are appended only during the install phase, not during the rebuild phase. To influence @electron/rebuild directly, see NativeModulesConfig.rebuildMode.

Example​

{ "npmArgs": ["--prefer-offline", "--ignore-scripts"] }

nsis?​

readonly optional nsis?: NsisOptions | null

NSIS one-click installer options.

NSIS (Nullsoft Scriptable Install System) is the default Windows installer format produced by electron-builder. It generates a lightweight, self-extracting .exe installer.

See​

NsisOptions

nsisWeb?​

readonly optional nsisWeb?: NsisWebOptions | null

NSIS web installer options.

Like the standard NSIS installer but the app payload is downloaded from a remote URL at install time rather than bundled into the .exe. Useful for very large apps or staged rollouts.

See​

NsisWebOptions

p5p?​

readonly optional p5p?: LinuxTargetSpecificOptions | null

Solaris IPS package options.

Produces a .p5p archive for the Solaris Image Packaging System (pkg).

pacman?​

readonly optional pacman?: PacmanOptions | null

Pacman package options.

Targets Arch Linux and Arch-based distributions (Manjaro, EndeavourOS, etc.). Produces a .pacman archive installable via pacman -U ./package.pacman.

See​

PacmanOptions

pkg?​

readonly optional pkg?: PkgOptions | null

macOS PKG flat-package installer options.

See​

PkgOptions

portable?​

readonly optional portable?: PortableOptions | null

Portable executable options.

Produces a single .exe that requires no installation — it extracts and runs directly.

See​

PortableOptions

productName?​

readonly optional productName?: string | null

The human-readable product name displayed in installers, the macOS dock, and the Windows Apps & Features list.

Unlike the name field in package.json, this value may contain spaces and other characters that are not allowed in npm package names.

Resolution order:

  1. productName inside the build configuration block.
  2. productName at the top level of package.json.
  3. name at the top level of package.json.

removePackageKeywords?​

readonly optional removePackageKeywords?: boolean

Whether to remove the keywords field from bundled package.json files.

The keywords array is only meaningful for package registry discoverability and has no runtime value inside a packaged Electron app. Removing it marginally reduces artifact size.

Default​

true

removePackageScripts?​

readonly optional removePackageScripts?: boolean

Whether to remove the scripts field from bundled package.json files.

Lifecycle scripts (preinstall, postinstall, etc.) have no meaning inside a packaged Electron app and can trigger unintended behaviour if any tooling inspects the bundled package.json. Removing them reduces artifact size and prevents accidental execution.

Default​

true

rpm?​

readonly optional rpm?: RpmOptions | null

RPM package options.

Targets Fedora, Red Hat Enterprise Linux, SUSE, and RPM-based distributions. Produces a .rpm archive installable via rpm -i or dnf install ./package.rpm.

See​

RpmOptions

snapcraft?​

readonly optional snapcraft?: SnapcraftOptions | null

Snapcraft configuration.

Selects the snapcraft base and provides per-core options:

  • base: "core18" | "core20" | "core22" — legacy bases; still functional but not recommended for new apps.
  • base: "core24" — modern base with the GNOME extension (recommended, requires Electron 25+).
  • base: "custom" — pass an existing snapcraft.yaml through unchanged; no plugs, extensions, or desktop files are injected.

Example​

{ "snapcraft": { "base": "core24", "core24": { "useLXD": true } } }

See​

SnapcraftOptions

squirrelWindows?​

readonly optional squirrelWindows?: SquirrelWindowsOptions | null

Squirrel.Windows auto-update installer options.

Requires the electron-builder-squirrel-windows optional dependency.

See​

SquirrelWindowsOptions

toolsets?​

readonly optional toolsets?: ToolsetConfig | null

Pinned versions of the binary toolsets electron-builder downloads and uses internally.

Each property selects a specific release of the corresponding tool bundle. Set a property to "0.0.0" to force the legacy bundle (pre-v27 behaviour). Leave a property unset (or set it to "latest") to use the modern default (newest bundle) for that toolset.

Note: Toolset versioning can drop intermediate releases (such as if a problem is discovered in a bundle). If you need to pin to a specific release, check the release notes for the toolset to ensure the version you specify is valid.

See​

ToolsetConfig

win?​

readonly optional win?: WindowsConfiguration | null

Windows-specific build options (signing, NSIS, icon, file associations, etc.).

See​

WindowsConfiguration