Common Configuration

Common configuration options shared across all platforms in electron-builder

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"
  }
}

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

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.

electronFuses.enableCookieEncryption · boolean

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:

• macOS Configuration
• Windows Configuration
• Linux Configuration

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.