Interface: Configuration
The root build configuration object passed to electron-builder.
Extends CommonConfiguration with top-level Electron-specific options, configuration inheritance/presets, and all per-platform build hooks.
Extends
Properties
afterAllArtifactBuild?
readonlyoptionalafterAllArtifactBuild?:string|Hook<BuildResult,string[]> |null
Called after all artifacts across all platforms/architectures have been built.
May return an array of additional file paths that should be treated as publish targets (i.e. uploaded to the configured publisher).
Receives a BuildResult.
Example
export default async function afterAllArtifactBuild(result) {
return ["/path/to/extra-file.txt"]
}
Inherited from
afterExtract?
readonlyoptionalafterExtract?:string|Hook<PackContext,void> |null
Called after the prebuilt Electron binary has been extracted to the staging directory but before the app files have been copied into it.
Use this hook to patch or augment the Electron binary itself (e.g. rename helper processes, inject native libraries) before the app payload is laid down on top.
Receives an AfterExtractContext.
Inherited from
afterPack?
readonlyoptionalafterPack?:string|Hook<PackContext,void> |null
Called after the app files have been copied into the staging directory (and ASAR created if applicable) but before signing and before the output archive/installer is built.
Use this hook to post-process the staged app bundle (e.g. strip debug symbols, inject platform-specific resources).
Receives an AfterPackContext.
Inherited from
afterSign?
readonlyoptionalafterSign?:string|Hook<PackContext,void> |null
Called after code signing but before the signed app is packed into the final
distributable format (e.g. before dmg is created from the signed .app).
Use this hook to perform post-sign validation or to add signed resources that are not part of the main app bundle.
Receives an AfterPackContext.
Inherited from
apk?
readonlyoptionalapk?:LinuxTargetSpecificOptions|null
Alpine Linux APK package options.
Produces an .apk archive installable via apk add --allow-untrusted ./package.apk.
Inherited from
appId?
readonlyoptionalappId?: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}
Inherited from
PlatformSpecificBuildOptions.appId
appImage?
readonlyoptionalappImage?: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
Inherited from
appx?
readonlyoptionalappx?: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
Inherited from
appxManifestCreated?
readonlyoptionalappxManifestCreated?:string|Hook<string,void> |null
Called after the AppX/MSIX manifest XML has been written to the staging directory but before
makeappx packages it.
The hook receives the path to the manifest file as a string. Use it to inject custom manifest extensions (capabilities, protocol handlers, etc.) not exposed through AppXOptions.
Inherited from
artifactBuildCompleted?
readonlyoptionalartifactBuildCompleted?:string|Hook<ArtifactCreated,void> |null
Called when an individual artifact has been successfully built and written to disk.
Use this hook to collect artifact paths, upload to custom destinations, or trigger post-processing steps.
Receives an ArtifactCreated.
Inherited from
artifactBuildStarted?
readonlyoptionalartifactBuildStarted?:string|Hook<ArtifactBuildStarted,void> |null
Called when an individual artifact build starts (e.g. just before a .dmg or .exe is
written to disk).
Receives an ArtifactBuildStarted.
Inherited from
artifactName?
readonlyoptionalartifactName?:string|null
The artifact file name template. Defaults to ${productName}-${version}.${ext} (some target can have other defaults, see corresponding options).
Inherited from
PlatformSpecificBuildOptions.artifactName
asar?
readonlyoptionalasar?:boolean|AsarOptions|null
Whether to package the application's source code into an archive, using Electron's archive format.
Node modules that must be unpacked will be detected automatically. Use AsarOptions.unpack to specify additional files to unpack.
Default
true
Inherited from
PlatformSpecificBuildOptions.asar
beforeBuild?
readonlyoptionalbeforeBuild?:string|Hook<BeforeBuildContext,boolean|void> |null
Called before dependencies are installed or native modules are rebuilt.
Return false (or a Promise that resolves to false) to skip the install/rebuild step
entirely — useful when you manage node_modules externally (e.g. in a CI pipeline that
restores them from cache). When not set, electron-builder proceeds with the normal
install/rebuild flow.
If this hook is provided and node_modules is missing, electron-builder will not perform
the production-dependencies check.
Receives a BeforeBuildContext.
Inherited from
beforePack?
readonlyoptionalbeforePack?:string|Hook<PackContext,void> |null
Called immediately before electron-builder begins packing the app for each platform/arch combination.
Use this hook to perform last-minute modifications to source files or build resources before they are read by the packager.
Receives a BeforePackContext.
Inherited from
buildNumber?
readonlyoptionalbuildNumber?: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.
Inherited from
CommonConfiguration.buildNumber
buildVersion?
readonlyoptionalbuildVersion?: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}.
Inherited from
CommonConfiguration.buildVersion
compression?
readonlyoptionalcompression?:CompressionLevel|null
The compression level. If you want to rapidly test build, store can reduce build time significantly. maximum doesn't lead to noticeable size difference, but increase build time.
Default
normal
Inherited from
PlatformSpecificBuildOptions.compression
concurrency?
readonlyoptionalconcurrency?: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
Inherited from
CommonConfiguration.concurrency
copyright?
readonlyoptionalcopyright?: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}
Inherited from
deb?
readonlyoptionaldeb?: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
Inherited from
defaultArch?
readonlyoptionaldefaultArch?:string
The default architecture to build for when no --arch flag is specified.
Defaults to the current machine's architecture.
Inherited from
PlatformSpecificBuildOptions.defaultArch
detectUpdateChannel?
readonlyoptionaldetectUpdateChannel?:boolean
Whether to infer update channel from application version pre-release components. e.g. if version 0.12.1-alpha.1, channel will be set to alpha. Otherwise to latest.
This does not apply to github publishing, which will never auto-detect the update channel.
Default
true
Inherited from
PlatformSpecificBuildOptions.detectUpdateChannel
directories?
readonlyoptionaldirectories?:MetadataDirectories|null
Overrides for input/output directory paths used during the build.
See
Inherited from
CommonConfiguration.directories
dmg?
readonlyoptionaldmg?:DmgOptions|null
macOS DMG disk image options (background image, window position, icon layout, licence, etc.).
See
Inherited from
downloadAlternateFFmpeg?
readonlyoptionaldownloadAlternateFFmpeg?: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.
Inherited from
CommonConfiguration.downloadAlternateFFmpeg
electronBranding?
readonlyoptionalelectronBranding?:ElectronBrandingOptions
Electron branding overrides.
Required only when packaging a custom Electron fork that ships a modified BRANDING.json
(e.g., a fork that renames the Electron Helper process or the Electron Framework).
Standard Electron builds do not need this.
electronDist?
readonlyoptionalelectronDist?:string|Hook<PrepareApplicationStageDirectoryOptions,string> |null
Override the source of the Electron distribution to stage.
Should return the path to either:
- A directory containing a pre-built, unpacked Electron app (e.g.
~/electron/out/R). - A directory containing Electron zip archives following the naming convention
electron-v${version}-${platformName}-${arch}.zip.
When not set, electron-builder downloads the official Electron release from GitHub (or the
mirror configured via electronDownload).
Receives a PrepareApplicationStageDirectoryOptions.
Inherited from
electronFuses?
readonlyoptionalelectronFuses?: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
Inherited from
CommonConfiguration.electronFuses
electronGet?
readonlyoptionalelectronGet?:ElectronGetOptions|null
Options forwarded to @electron/get when downloading the
Electron distribution to package.
electronLanguages?
readonlyoptionalelectronLanguages?:string|string[]
The electron locales to keep. By default, all Electron locales used as-is.
Inherited from
PlatformSpecificBuildOptions.electronLanguages
electronUpdaterCompatibility?
readonlyoptionalelectronUpdaterCompatibility?:string|null
The electron-updater compatibility semver range.
Inherited from
PlatformSpecificBuildOptions.electronUpdaterCompatibility
electronVersion?
optionalelectronVersion?:string|null
The Electron version to package against.
Defaults to the version of the electron (or electron-prebuilt) dependency declared in
package.json. Set this explicitly only when the installed Electron version is not the one
you want to package against (e.g., in monorepos where the Electron dependency lives in a
different workspace).
executableName?
readonlyoptionalexecutableName?:string|null
The executable name. Defaults to productName
Note: Except for Linux, where this would constitute a breaking change in previous behavior and lead to both invalid executable names and Desktop files. Ref comments in: https://github.com/electron-userland/electron-builder/pull/9068
Inherited from
PlatformSpecificBuildOptions.executableName
extends?
optionalextends?:string|string[] |null
One or more configuration presets or file paths to merge into this configuration.
Accepts a string or array of strings, each of which is either:
- A built-in preset name (
"react-cra"is the only currently supported value). - A path to a JS/JSON config file relative to the project directory.
Configs are merged left-to-right using a deep-assign strategy that properly combines files
glob patterns rather than replacing them.
The react-cra preset is applied automatically when react-scripts is found in
dependencies. Set extends: null to opt out of automatic preset detection.
extraFiles?
optionalextraFiles?:string|FileSet| (string|FileSet)[] |null
The same as extraResources but copy into the app's content directory (Contents for MacOS, root directory for Linux and Windows).
Inherited from
PlatformSpecificBuildOptions.extraFiles
extraMetadata?
readonlyoptionalextraMetadata?: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" } }
Inherited from
CommonConfiguration.extraMetadata
extraResources?
optionalextraResources?:string|FileSet| (string|FileSet)[] |null
A glob patterns relative to the project directory, when specified, copy the file or directory with matching names directly into the app's resources directory (Contents/Resources for MacOS, resources for Linux and Windows).
File patterns (and support for from and to fields) the same as for files.
Inherited from
PlatformSpecificBuildOptions.extraResources
fileAssociations?
readonlyoptionalfileAssociations?:FileAssociation|FileAssociation[]
The file associations.
Inherited from
PlatformSpecificBuildOptions.fileAssociations
files?
optionalfiles?:string|FileSet| (string|FileSet)[] |null
A glob patterns relative to the app directory, which specifies which files to include when copying files to create the package.
Defaults to:
[
"**/*",
"!**/node_modules/*/{CHANGELOG.md,README.md,README,readme.md,readme}",
"!**/node_modules/*/{test,__tests__,tests,powered-test,example,examples}",
"!**/node_modules/*.d.ts",
"!**/node_modules/.bin",
"!**/*.{iml,o,hprof,orig,pyc,pyo,rbc,swp,csproj,sln,xproj}",
"!.editorconfig",
"!**/._*",
"!**/{.DS_Store,.git,.hg,.svn,CVS,RCS,SCCS,.gitignore,.gitattributes}",
"!**/{__pycache__,thumbs.db,.flowconfig,.idea,.vs,.nyc_output}",
"!**/{appveyor.yml,.travis.yml,circle.yml}",
"!**/{npm-debug.log,yarn.lock,.yarn-integrity,.yarn-metadata.json}"
]
Development dependencies are never copied in any case. You don't need to ignore it explicitly. Hidden files are not ignored by default, but all files that should be ignored, are ignored by default.
Default pattern **/* is not added to your custom if some of your patterns is not ignore (i.e. not starts with !). package.json and **/node_modules/**/* (only production dependencies will be copied) is added to your custom in any case. All default ignores are added in any case — you don't need to repeat it if you configure own patterns.
May be specified in the platform options (e.g. in the mac).
You may also specify custom source and destination directories by using FileSet objects instead of simple glob patterns.
[
{
"from": "path/to/source",
"to": "path/to/destination",
"filter": ["**/*", "!foo/*.js"]
}
]
You can use file macros in the from and to fields as well. from and to can be files and you can use this to rename a file while packaging.
Inherited from
PlatformSpecificBuildOptions.files
flatpak?
readonlyoptionalflatpak?:FlatpakOptions|null
Flatpak options.
Flatpak is a sandboxed application distribution format for Linux distributed via Flathub or self-hosted OSTree repositories.
See
Inherited from
forceCodeSigning?
readonlyoptionalforceCodeSigning?: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
Inherited from
PlatformSpecificBuildOptions.forceCodeSigning
freebsd?
readonlyoptionalfreebsd?:LinuxTargetSpecificOptions|null
FreeBSD pkg package options.
Produces a .pkg archive for the FreeBSD package manager.
Inherited from
generateUpdatesFilesForAllChannels?
readonlyoptionalgenerateUpdatesFilesForAllChannels?:boolean
Please see Building and Releasing using Channels.
Default
false
Inherited from
PlatformSpecificBuildOptions.generateUpdatesFilesForAllChannels
includePdb?
readonlyoptionalincludePdb?: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
Inherited from
CommonConfiguration.includePdb
linux?
readonlyoptionallinux?: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
Inherited from
mac?
readonlyoptionalmac?:MacConfiguration|null
macOS-specific build options (signing, entitlements, notarization, target categories, etc.).
See
Inherited from
mas?
readonlyoptionalmas?:MasConfiguration|null
macOS App Store (MAS) submission options.
See
Inherited from
masDev?
readonlyoptionalmasDev?:MasConfiguration|null
macOS App Store development-signing options (mas-dev target).
Used for local testing of MAS builds without submitting to the store.
See
Inherited from
msi?
readonlyoptionalmsi?: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
Inherited from
msiProjectCreated?
readonlyoptionalmsiProjectCreated?:string|Hook<string,void> |null
Called after the WiX MSI project XML has been written to a temporary directory but before
candle.exe / light.exe compile it into a .msi package.
The hook receives the path to the project directory as a string. Use it to patch the generated
.wxs files for customizations not exposed through electron-builder's options.
Inherited from
msiWrapped?
readonlyoptionalmsiWrapped?: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
Inherited from
CommonConfiguration.msiWrapped
nativeModules?
readonlyoptionalnativeModules?: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
Inherited from
CommonConfiguration.nativeModules
npmArgs?
readonlyoptionalnpmArgs?: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"] }
Inherited from
nsis?
readonlyoptionalnsis?: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
Inherited from
nsisWeb?
readonlyoptionalnsisWeb?: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
Inherited from
onNodeModuleFile?
readonlyoptionalonNodeModuleFile?:string|Hook<string,boolean|void> |null
Called for every file inside each node_modules package directory as electron-builder
decides whether to include it in the packaged app.
Return true to force-include the file regardless of the default exclusion rules.
Return false or undefined to let electron-builder apply its normal filtering logic.
Receives the absolute path of the file as a string.
Inherited from
p5p?
readonlyoptionalp5p?:LinuxTargetSpecificOptions|null
Solaris IPS package options.
Produces a .p5p archive for the Solaris Image Packaging System (pkg).
Inherited from
pacman?
readonlyoptionalpacman?: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
Inherited from
pkg?
readonlyoptionalpkg?:PkgOptions|null
macOS PKG flat-package installer options.
See
Inherited from
portable?
readonlyoptionalportable?:PortableOptions|null
Portable executable options.
Produces a single .exe that requires no installation — it extracts and runs directly.
See
Inherited from
productName?
readonlyoptionalproductName?: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:
productNameinside thebuildconfiguration block.productNameat the top level ofpackage.json.nameat the top level ofpackage.json.
Inherited from
CommonConfiguration.productName
protocols?
The URL protocol schemes.
Inherited from
PlatformSpecificBuildOptions.protocols
publish?
optionalpublish?:Publish
Publisher configuration. See Auto Update for more information.
Inherited from
PlatformSpecificBuildOptions.publish
releaseInfo?
readonlyoptionalreleaseInfo?:ReleaseInfo
The release info. Intended for command line usage:
-c.releaseInfo.releaseNotes="new features"
Inherited from
PlatformSpecificBuildOptions.releaseInfo
removePackageKeywords?
readonlyoptionalremovePackageKeywords?: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
Inherited from
CommonConfiguration.removePackageKeywords
removePackageScripts?
readonlyoptionalremovePackageScripts?: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
Inherited from
CommonConfiguration.removePackageScripts
rpm?
readonlyoptionalrpm?: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
Inherited from
snapcraft?
readonlyoptionalsnapcraft?: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 existingsnapcraft.yamlthrough unchanged; no plugs, extensions, or desktop files are injected.
Example
{ "snapcraft": { "base": "core24", "core24": { "useLXD": true } } }
See
Inherited from
squirrelWindows?
readonlyoptionalsquirrelWindows?:SquirrelWindowsOptions|null
Squirrel.Windows auto-update installer options.
Requires the electron-builder-squirrel-windows optional dependency.
See
Inherited from
CommonConfiguration.squirrelWindows
target?
readonlyoptionaltarget?:string|TargetConfiguration| (string|TargetConfiguration)[] |null
The build target(s) for this platform. Can be a target name string, a TargetConfiguration object, or an array of either. Available targets depend on the platform — see platform-specific options (e.g. MacConfiguration.target, WindowsConfiguration.target, LinuxConfiguration.target).
Inherited from
PlatformSpecificBuildOptions.target
toolsets?
readonlyoptionaltoolsets?: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 to
null) to use the modern default for that toolset.
See
Inherited from
win?
readonlyoptionalwin?:WindowsConfiguration|null
Windows-specific build options (signing, NSIS, icon, file associations, etc.).