electron-builder configuration can be defined

  • in the package.json file of your project using the build key on the top level: `json "build": { "appId": "com.example.app" } `
  • or through the --config <path/to/yml-or-json5-or-toml> option (defaults to electron-builder.yml (or json, or json5, or toml)). `yaml appId: "com.example.app" `

    If you want to use toml, please install yarn add toml --dev.

Most of the options accept null — for example, to explicitly set that DMG icon must be default volume icon from the OS and default rules must be not applied (i.e. use application icon as DMG icon), set dmg.icon to null.

Artifact File Name Template

${ext} macro is supported in addition to file macros.

Environment Variables from File

Env file electron-builder.env in the current dir (example). Supported only for CLI usage.

How to Read Docs

  • Name of optional property is normal, required is bold.
  • Type is specified after property name: Array<String> | String. Union like this means that you can specify or string (***", "!foo.js"]).


  • appId = com.electron.${name} String - The application id. Used as CFBundleIdentifier for MacOS and as Application User Model ID for Windows (NSIS target only, Squirrel.Windows not supported). It is strongly recommended that an explicit ID is set.
  • productName String - As name, but allows you to specify a product name for your executable which contains spaces and other special characters not allowed in the name property.
  • copyright = Copyright © year ${author} String - The human-readable copyright line for the app.

  • directories

    • buildResources = build String - The path to build resources.

      Please note — build resources is not packed into the app. If you need to use some files, e.g. as tray icon, please include required files explicitly: "files": ["**/*", "build/icon.*"]

    • output = dist String - The output directory.
    • app String - The application directory (containing the application package.json), defaults to app, www or working directory.

  • winWindowsConfiguration - Options related to how build Windows targets.
  • nsisNsisOptions
  • nsisWeb - Web Installer options. Inherits NsisOptions options.

    • appPackageUrl String - The application package download URL. Optional — by default computed using publish configuration.

      URL like https://example.com/download/latest allows web installer to be version independent (installer will download latest application package). Please note — it is full URL.

      Custom X-Arch http header is set to 32 or 64.

    • artifactName String - The artifact file name template. Defaults to ${productName} Web Setup ${version}.${ext}.
  • portable - Portable options.
  • appxAppXOptions
  • squirrelWindowsSquirrelWindowsOptions

  • buildDependenciesFromSource = false Boolean - Whether to build the application native dependencies from source.
  • nodeGypRebuild = false Boolean - Whether to execute node-gyp rebuild before starting to package the app.

    Don't usenpm (neither .npmrc) for configuring electron headers. Use electron-builder node-gyp-rebuild instead.

  • npmArgs Array<String> | String - Additional command line arguments to use when installing app native deps.
  • npmRebuild = true Boolean - Whether to rebuild native dependencies before starting to package the app.

  • buildVersion String - The build version. Maps to the CFBundleVersion on macOS, and FileVersion metadata property on Windows. Defaults to the version. If TRAVIS_BUILD_NUMBER or APPVEYOR_BUILD_NUMBER or CIRCLE_BUILD_NUM or BUILD_NUMBER or bamboo.buildNumber env defined, it will be used as a build version (version.build_number).
  • electronCompile Boolean - Whether to use electron-compile to compile app. Defaults to true if electron-compile in the dependencies. And false if in the devDependencies or doesn't specified.
  • electronDist String - The path to custom Electron build (e.g. ~/electron/out/R).
  • electronDownload - The electron-download options.
    • cache String - The cache location.
    • mirror String - The mirror.
    • quiet Boolean
    • strictSSL Boolean
    • verifyChecksum Boolean
  • electronVersion String - The version of electron you are packaging for. Defaults to version of electron, electron-prebuilt or electron-prebuilt-compile dependency.
  • extends String - The name of a built-in configuration preset or path to config file (relative to project dir). Currently, only react-cra is supported.

    If react-scripts in the app dev dependencies, react-cra will be set automatically. Set to null to disable automatic detection.

  • extraMetadata any - Inject properties to package.json.

  • forceCodeSigning = false Boolean - Whether to fail if the application is not signed (to prevent unsigned app if code signing configuration is not correct).
  • muonVersion String - The version of muon you are packaging for.

  • afterPack (context: AfterPackContext) => Promise | null - The function (or path to file or module id) to be run after pack (but before pack into distributable format and sign).
  • beforeBuild (context: BeforeBuildContext) => Promise | null - The function (or path to file or module id) to be run before dependencies are installed or rebuilt. Works when npmRebuild is set to true. Resolving to false will skip dependencies install or rebuild.

Following options can be set also per platform (top-level keys mac, linux and win).

{% include "/generated/PlatformSpecificBuildOptions.md" %}


Some standard fields should be defined in the package.json.

{% include "/generated/Metadata.md" %}

Build Version Management

CFBundleVersion (macOS) and FileVersion (Windows) will be set automatically to version.build_number on CI server (Travis, AppVeyor, CircleCI and Bamboo supported).