Common Configuration

electron-builder configuration can be defined in multiple ways:

In the package.json file using the build key:

"build": {
  "appId": "com.example.app"
}

Through the --config <path/to/yml-or-json5-or-toml-or-js> option (defaults to electron-builder.yml):
```
appId: "com.example.app"
```

Supported formats: json, json5, toml, yaml, and js/ts (exported configuration or function)

If using a js file, do not name it electron-builder.js as it will conflict with the electron-builder package name.

Configuration Methods

package.json Configuration

{
  "name": "my-app",
  "version": "1.0.0",
  "build": {
    "appId": "com.example.myapp",
    "productName": "My Application",
    "copyright": "Copyright © 2024 ${author}",
    "directories": {
      "output": "dist",
      "buildResources": "build"
    }
  }
}

electron-builder.yml Configuration

appId: com.example.myapp
productName: My Application
copyright: "Copyright © 2024 ${author}"
directories:
  output: dist
  buildResources: build
mac:
  category: public.app-category.productivity
win:
  target: nsis
linux:
  target: AppImage

JavaScript Configuration

// electron-builder.config.js
module.exports = {
  appId: "com.example.myapp",
  productName: "My Application",
  directories: {
    output: "dist"
  },
  mac: {
    category: "public.app-category.productivity"
  }
}

Environment Variables

You can use an electron-builder.env file in the current directory for environment variables. This is supported only for CLI usage.

Common Configuration Options

appId

string

default:"com.electron.${name}"

The application id. Used as:

CFBundleIdentifier for macOS
Application User Model ID for Windows (NSIS target only)

It is strongly recommended that an explicit ID is set.

{
  "build": {
    "appId": "com.example.myapp"
  }
}

productName

string

The product name for your executable. Can contain spaces and special characters not allowed in the name property.If not specified in build configuration, the top-level productName from package.json is used. If that’s not specified, the name property is used.

{
  "build": {
    "productName": "My Awesome Application"
  }
}

string

The human-readable copyright line for the app.

{
  "build": {
    "copyright": "Copyright © 2024 My Company Inc."
  }
}

directories

object

Directories for build resources and output.

directories.buildResources

string

default:"build"

The path to build resources (icons, background images, etc.).

Build resources are not packed into the app. If you need to use files at runtime (e.g., tray icon), include them explicitly using the files option.

{
  "build": {
    "directories": {
      "buildResources": "resources"
    }
  }
}

directories.output

string

default:"dist"

The output directory. Supports file macros.

{
  "build": {
    "directories": {
      "output": "release"
    }
  }
}

directories.app

string

The application directory containing the application package.json. Defaults to app, www, or working directory.

{
  "build": {
    "directories": {
      "app": "src"
    }
  }
}

buildVersion

string

The build version. Maps to:

CFBundleVersion on macOS
FileVersion metadata property on Windows

Defaults to the version from package.json.If not defined but buildNumber is defined, it will be set to version.buildNumber.

{
  "build": {
    "buildVersion": "1.2.3.456"
  }
}

buildNumber

string

The build number. Maps to the --iteration flag for builds using FPM on Linux.If not defined, falls back to environment variables:

BUILD_NUMBER
TRAVIS_BUILD_NUMBER
APPVEYOR_BUILD_NUMBER
CIRCLE_BUILD_NUM
BUILD_BUILDNUMBER
CI_PIPELINE_IID

{
  "build": {
    "buildNumber": "456"
  }
}

electronVersion

string

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

{
  "build": {
    "electronVersion": "28.0.0"
  }
}

extraMetadata

object

Inject properties to package.json. Useful for setting version or other metadata dynamically.

{
  "build": {
    "extraMetadata": {
      "version": "1.2.3",
      "main": "app.js"
    }
  }
}

extends

string | string[]

The name of a built-in configuration preset (currently only react-cra is supported) or paths to config files.Allows mixing configs from multiple files, properly combining files glob patterns.If react-scripts is in app dependencies, react-cra is set automatically. Set to null to disable.

{
  "build": {
    "extends": ["./base-config.json", "./platform-config.json"]
  }
}

Native Dependencies

buildDependenciesFromSource

boolean

default:false

Whether to build the application native dependencies from source.

{
  "build": {
    "buildDependenciesFromSource": true
  }
}

nodeGypRebuild

boolean

default:false

Whether to execute node-gyp rebuild before starting to package the app.

Don’t use npm or .npmrc for configuring electron headers. Use electron-builder node-gyp-rebuild instead.

{
  "build": {
    "nodeGypRebuild": true
  }
}

npmRebuild

boolean

default:true

Whether to rebuild native dependencies before starting to package the app.

{
  "build": {
    "npmRebuild": false
  }
}

nativeRebuilder

string

default:"sequential"

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

{
  "build": {
    "nativeRebuilder": "parallel"
  }
}

npmArgs

string | string[]

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

{
  "build": {
    "npmArgs": ["--legacy-peer-deps"]
  }
}

Code Signing

forceCodeSigning

boolean

default:false

Whether to fail if the application is not signed (prevents unsigned app if code signing configuration is incorrect).

{
  "build": {
    "forceCodeSigning": true
  }
}

Advanced Options

electronDownload

object

The electron-download options.

{
  "build": {
    "electronDownload": {
      "mirror": "https://npmmirror.com/mirrors/electron/"
    }
  }
}

electronBranding

object

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

{
  "build": {
    "electronBranding": {
      "projectName": "MyElectron"
    }
  }
}

downloadAlternateFFmpeg

boolean

default:false

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

{
  "build": {
    "downloadAlternateFFmpeg": true
  }
}

includePdb

boolean

default:false

Whether to include PDB files (Windows debugging symbols).

{
  "build": {
    "includePdb": true
  }
}

removePackageScripts

boolean

default:true

Whether to remove scripts field from package.json files.

{
  "build": {
    "removePackageScripts": false
  }
}

removePackageKeywords

boolean

default:true

Whether to remove keywords field from package.json files.

{
  "build": {
    "removePackageKeywords": false
  }
}

disableSanityCheckAsar

boolean

default:false

Whether to disable sanity check of asar package. Useful for custom Electron forks that implement their own encrypted integrity validation.

{
  "build": {
    "disableSanityCheckAsar": true
  }
}

Electron Fuses

electronFuses

object

Options to pass to @electron/fuses. Fuses are security and feature toggles in Electron.

electronFuses.runAsNode

boolean

Toggles whether the ELECTRON_RUN_AS_NODE environment variable is respected.

If disabled, process.fork won’t work as expected. Use Utility Processes instead.

Toggles whether the cookie store on disk is encrypted using OS level cryptography keys.

This is a one-way transition. Enabling it encrypts unencrypted cookies, but disabling it afterward will corrupt the cookie store.

electronFuses.enableNodeOptionsEnvironmentVariable

boolean

Toggles whether the NODE_OPTIONS and NODE_EXTRA_CA_CERTS environment variables are respected.

electronFuses.enableNodeCliInspectArguments

boolean

Toggles whether the --inspect, --inspect-brk, etc. flags are respected.

electronFuses.enableEmbeddedAsarIntegrityValidation

boolean

Toggles validation of the app.asar file content when loaded.Supported on:

macOS (Electron >= 16.0.0)
Windows (Electron >= 30.0.0)

See Asar Integrity documentation.

electronFuses.onlyLoadAppFromAsar

boolean

Changes the search order to only load from app.asar. Ensures only validated code is loaded when combined with enableEmbeddedAsarIntegrityValidation.

electronFuses.loadBrowserProcessSpecificV8Snapshot

boolean

Changes which V8 snapshot file is used for the browser process (browser_v8_context_snapshot.bin).

electronFuses.grantFileProtocolExtraPrivileges

boolean

Toggles extra privileges for pages loaded from the file:// protocol.

Consider serving local files from custom protocols instead. See security best practices.

{
  "build": {
    "electronFuses": {
      "runAsNode": false,
      "enableCookieEncryption": true,
      "enableNodeOptionsEnvironmentVariable": false,
      "enableNodeCliInspectArguments": false,
      "enableEmbeddedAsarIntegrityValidation": true,
      "onlyLoadAppFromAsar": true
    }
  }
}

Toolset Configuration

toolsets

object

Configuration of toolsets utilized by electron-builder.

toolsets.winCodeSign

string

default:"0.0.0"

win-codesign version to use for signing Windows artifacts.Options:

0.0.0 (stable, winCodeSign)
1.0.0 (beta, Windows Kits 10.0.26100.0)
1.1.0 (beta)

See releases.

toolsets.appimage

string

default:"0.0.0"

appimage bundle version to use for AppImage packaging and runtime.Options:

0.0.0 (legacy toolset)
1.0.2 (beta, Runtime 20251108)

See releases.

{
  "build": {
    "toolsets": {
      "winCodeSign": "1.1.0",
      "appimage": "1.0.2"
    }
  }
}

Concurrency

concurrency

object

Experimental configuration for concurrent builds.

concurrency.jobs

number

default:1

The maximum number of concurrent jobs to run.

{
  "build": {
    "concurrency": {
      "jobs": 4
    }
  }
}

Framework-Specific Options

Proton Native

To package Proton Native apps, set nodeVersion to current or a specific NodeJS version.

Currently, only macOS and Linux are supported for Proton Native.

{
  "build": {
    "nodeVersion": "current",
    "framework": "proton"
  }
}

framework

string

default:"electron"

The framework name. Options: electron, proton, libui.

nodeVersion

string

For libui-based frameworks only. The version of NodeJS you are packaging for. Set to current to use the Node.js version you’re running.

launchUiVersion

boolean | string

For libui-based frameworks only. The version of LaunchUI you are packaging for (Windows only).

Build Version Management

CFBundleVersion (macOS) and FileVersion (Windows) will be set automatically to version.build_number on CI servers:

Travis CI
AppVeyor
CircleCI
Bamboo
GitLab CI
GitHub Actions

Overridable Options

Many options can be overridden per platform using the top-level mac, linux, and win keys. See:

Artifact File Name Template

The ${ext} macro is supported in addition to file macros for artifact naming.

Notes

Most options accept null to explicitly unset a value. For example, to use the default OS volume icon instead of the application icon for DMG, set dmg.icon to null.

Common

macOS

Windows

Linux

Publishing

Configuration Methods

package.json Configuration

electron-builder.yml Configuration

JavaScript Configuration

Environment Variables

Common Configuration Options

Native Dependencies

Code Signing

Advanced Options

Electron Fuses

Toolset Configuration

Concurrency

Framework-Specific Options

Proton Native

Build Version Management

Overridable Options

Artifact File Name Template

Notes

Build docs developers (and LLMs) love

Common

macOS

Windows

Linux

Publishing

​Configuration Methods

​package.json Configuration

​electron-builder.yml Configuration

​JavaScript Configuration

​Environment Variables

​Common Configuration Options

​Native Dependencies

​Code Signing

​Advanced Options

​Electron Fuses

​Toolset Configuration

​Concurrency

​Framework-Specific Options

​Proton Native

​Build Version Management

​Overridable Options

​Artifact File Name Template

​Notes

Build docs developers (and LLMs) love

Configuration Methods

package.json Configuration

electron-builder.yml Configuration

JavaScript Configuration

Environment Variables

Common Configuration Options

Native Dependencies

Code Signing

Advanced Options

Electron Fuses

Toolset Configuration

Concurrency

Framework-Specific Options

Proton Native

Build Version Management

Overridable Options

Artifact File Name Template

Notes