Configuration Interface

Main electron-builder configuration interface

The Configuration interface defines all available options for configuring electron-builder.

Source: packages/app-builder-lib/src/configuration.ts:202

Interface Definition

interface Configuration extends CommonConfiguration, PlatformSpecificBuildOptions, Hooks {
  // Configuration properties
}

The Configuration interface extends:

• CommonConfiguration - Common configuration options
• PlatformSpecificBuildOptions - File patterns and build options
• Hooks - Lifecycle hooks

Application Metadata

appId · string | null · default: "com.electron.${name}"

The application ID. Used as CFBundleIdentifier for macOS and Application User Model ID for Windows (NSIS only). It is strongly recommended that an explicit ID is set.

Example: "com.mycompany.myapp"

productName · string | null

The product name for your executable. Allows spaces and special characters not allowed in the name property. If not specified, uses productName from top-level package.json, or falls back to name.

Example: "My Application"

copyright · string | null · default: "Copyright © year ${author}"

The human-readable copyright line for the app.

Example: "Copyright © 2024 My Company"

Framework Configuration

electronVersion · string | null

The version of Electron you are packaging for. Defaults to version of electron, electron-prebuilt, or electron-prebuilt-compile dependency.

Example: "28.0.0"

electronDownload · ElectronDownloadOptions

Options for downloading Electron.

Show properties

mirror · string

CDN mirror URL.

customDir · string

Custom directory path on mirror.

customFilename · string

Custom filename.

electronBranding · ElectronBrandingOptions

The branding used by Electron’s distributables. Needed if a fork has modified Electron’s BRANDING.json file.

Show properties

projectName · string

Project name.

productName · string

Product name.

framework · string | null · default: "electron"

The framework name. One of electron, proton, or libui.

electronCompile · boolean

Whether to use electron-compile. Defaults to true if electron-compile is in dependencies, false if in devDependencies or not specified.

Directories

directories · MetadataDirectories | null

Directory configuration.

Show properties

buildResources · string | null · default: "build"

Path to build resources directory. These files are not packed into the app.

output · string | null · default: "dist"

Output directory for built artifacts. Supports file macros.

app · string | null

Application directory containing package.json. Defaults to app, www, or working directory.

Build Configuration

extends · Array<string> | string | null

Name of a built-in preset (currently only react-cra) or paths to config files to extend. Automatically set to react-cra if react-scripts is in dependencies. Set to null to disable.

buildDependenciesFromSource · boolean · default: "false"

Whether to build native dependencies from source.

nodeGypRebuild · boolean · default: "false"

Whether to execute node-gyp rebuild before packaging.

npmRebuild · boolean · default: "true"

Whether to rebuild native dependencies before packaging.

nativeRebuilder · 'legacy' | 'sequential' | 'parallel' | null · default: "sequential"

Use legacy app-builder binary for installing native dependencies, or @electron/rebuild in sequential or parallel compilation modes.

npmArgs · Array<string> | string | null

Additional command line arguments to use when installing app native deps.

Version Configuration

buildNumber · string | null

The build number. Maps to --iteration flag for FPM on Linux. Falls back to BUILD_NUMBER, TRAVIS_BUILD_NUMBER, APPVEYOR_BUILD_NUMBER, CIRCLE_BUILD_NUM, or BUILD_BUILDNUMBER environment variables.

buildVersion · string | null

The build version. Maps to CFBundleVersion on macOS and FileVersion on Windows. Defaults to version. If not defined but buildNumber is, uses version.buildNumber.

Platform-Specific Options

macOS

mac · MacConfiguration | null

Options for building macOS targets.

mas · MasConfiguration | null

Mac Application Store (MAS) options.

masDev · MasConfiguration | null

MAS development options for mas-dev target.

dmg · DmgOptions | null

macOS DMG target options.

pkg · PkgOptions | null

macOS PKG target options.

Windows

win · WindowsConfiguration | null

Options for building Windows targets.

nsis · NsisOptions | null

NSIS installer options.

nsisWeb · NsisWebOptions | null

NSIS web installer options.

portable · PortableOptions | null

Portable app options.

appx · AppXOptions | null

AppX package options.

msi · MsiOptions | null

MSI installer options (private).

squirrelWindows · SquirrelWindowsOptions | null

Squirrel.Windows installer options.

Linux

linux · LinuxConfiguration | null

Options for building Linux targets.

deb · DebOptions | null

Debian package options.

snap · SnapOptions | null

Snap package options.

appImage · AppImageOptions | null

AppImage options.

flatpak · FlatpakOptions | null

Flatpak options.

pacman · LinuxTargetSpecificOptions | null

Pacman package options.

rpm · LinuxTargetSpecificOptions | null

RPM package options.

Code Signing

forceCodeSigning · boolean · default: "false"

Whether to fail if the app is not code signed.

downloadAlternateFFmpeg · boolean

Whether to download the alternate FFmpeg library from Electron’s release assets and replace the default FFmpeg library prior to signing.

Advanced Options

extraMetadata · any

Inject properties to package.json. Can override any package.json fields.

Example:

{
  "extraMetadata": {
    "version": "1.0.0-beta.1"
  }
}

includePdb · boolean · default: "false"

Whether to include PDB files (Windows debug symbols).

removePackageScripts · boolean · default: "true"

Whether to remove scripts field from package.json files.

removePackageKeywords · boolean · default: "true"

Whether to remove keywords field from package.json files.

disableSanityCheckAsar · boolean · default: "false"

Whether to disable sanity check of asar package. Useful for custom Electron forks with encrypted integrity validation.

Electron Fuses

electronFuses · FuseOptionsV1 | null

Options to pass to @electron/fuses. See Electron Fuses.

Show properties

runAsNode · boolean

Toggle ELECTRON_RUN_AS_NODE environment variable support.

enableCookieEncryption · boolean

Enable cookie store encryption.

enableNodeOptionsEnvironmentVariable · boolean

Enable NODE_OPTIONS and NODE_EXTRA_CA_CERTS environment variables.

enableNodeCliInspectArguments · boolean

Enable Node.js inspector CLI arguments.

enableEmbeddedAsarIntegrityValidation · boolean

Enable ASAR integrity validation.

onlyLoadAppFromAsar · boolean

Only load app from app.asar.

loadBrowserProcessSpecificV8Snapshot · boolean

Use browser-specific V8 snapshot.

grantFileProtocolExtraPrivileges · boolean

Grant extra privileges to file:// protocol.

Toolsets

toolsets · ToolsetConfig | null

Configuration of toolsets utilized by electron-builder.

Show properties

winCodeSign · '0.0.0' | '1.0.0' | '1.1.0' | null · default: "0.0.0"

win-codesign version for signing Windows artifacts.

appimage · '0.0.0' | '1.0.2' | null · default: "0.0.0"

AppImage bundle version for packaging and runtime.

Concurrency

concurrency · Concurrency | null

Experimental configuration for concurrent builds.

Show properties

jobs · number · default: "1"

Maximum number of concurrent jobs to run.

Example Configuration

{
  "appId": "com.example.myapp",
  "productName": "My Application",
  "copyright": "Copyright © 2024 My Company",
  
  "directories": {
    "output": "dist",
    "buildResources": "build"
  },
  
  "files": [
    "dist/**/*",
    "package.json"
  ],
  
  "mac": {
    "category": "public.app-category.developer-tools",
    "target": ["dmg", "zip"]
  },
  
  "win": {
    "target": ["nsis", "portable"]
  },
  
  "linux": {
    "target": ["AppImage", "deb"],
    "category": "Development"
  },
  
  "nsis": {
    "oneClick": false,
    "allowToChangeInstallationDirectory": true
  },
  
  "publish": {
    "provider": "github",
    "owner": "my-org",
    "repo": "my-repo"
  }
}

See Also

• PackagerOptions Interface
• Platform-Specific Options
• Programmatic Usage