Options

develar edited this page Jan 17, 2017 · 132 revisions

electron-builder configuration can be defined in the package.json file of your project or through the --config <path/to/yml> option (defaults to electron-builder.yml). If you'd like to use your package.json to store config, the build key should be used on the top level.

For example, to change icon location for DMG:

"build": {
  "dmg": {
    "contents": [
      {
          "x": 130,
          "y": 220
      },
      {
        "x": 410,
        "y": 220,
        "type": "link",
        "path": "/Applications"
      }
    ]
  }
}

As you can see, you need to customize MacOS options only if you want to provide custom x, y. Don't customize paths to background and icon, — just follow conventions.

Configuration Options

Name Description
appId

The application id. Used as CFBundleIdentifier for MacOS and as Application User Model ID for Windows (NSIS target only, Squirrel.Windows not supported).

Defaults to com.electron.${name}. It is strongly recommended that an explicit ID be set.

copyright The human-readable copyright line for the app. Defaults to Copyright © year author.
productName See AppMetadata.productName.
files

A glob patterns relative to the app directory, which specifies which files to include when copying files to create the package.

See File Patterns.

extraResources

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/Windows).

Glob rules the same as for files.

extraFiles The same as extraResources but copy into the app's content directory (Contents for MacOS, root directory for Linux/Windows).
asar

Whether to package the application’s source code into an archive, using Electron’s archive format. Defaults to true. Node modules, that must be unpacked, will be detected automatically, you don’t need to explicitly set asarUnpack - please file issue if this doesn’t work.

asarUnpack A glob patterns relative to the app directory, which specifies which files to unpack when creating the asar archive.
compression The compression level, one of store, normal, maximum (default: normal). If you want to rapidly test build, store can reduce build time significantly.
afterPack programmatic API only The function to be run after pack (but before pack into distributable format and sign). Promise must be returned.
beforeBuild programmatic API only The function to be run before dependencies are installed or rebuilt. Works when npmRebuild is set to true. Promise must be returned. Resolving to false will skip dependencies install or rebuild.
npmRebuild Whether to rebuild native dependencies (npm rebuild) before starting to package the app. Defaults to true.
npmSkipBuildFromSource Whether to omit using --build-from-source flag when installing app native deps. Defaults to false.
npmArgs Additional command line arguments to use when installing app native deps. Defaults to null.
nodeGypRebuild Whether to execute node-gyp rebuild before starting to package the app. Defaults to false.
electronDist The path to custom Electron build (e.g. ~/electron/out/R). Only macOS supported, file issue if need for Linux or Windows.
electronDownload The electron-download options.
publish See publish.
forceCodeSigning Whether to fail if application will be not signed (to prevent unsigned app if code signing configuration is not correct).
electronVersion The version of electron you are packaging for. Defaults to version of electron, electron-prebuilt or electron-prebuilt-compile dependency.

appx

Please see Windows AppX docs.

Name Description
backgroundColor The background color of the app tile. Please see Visual Elements.
publisher Describes the publisher information. The Publisher attribute must match the publisher subject information of the certificate used to sign a package. For now, required.
displayName A friendly name that can be displayed to users. Corresponds to Properties.DisplayName.
publisherDisplayName A friendly name for the publisher that can be displayed to users. Corresponds to Properties.PublisherDisplayName.
identityName Describes the contents of the package. The Name attribute is case-sensitive. Corresponds to Identity.Name.

directories

Name Description
buildResources The path to build resources, defaults to build.
output The output directory, defaults to dist.
app The application directory (containing the application package.json), defaults to app, www or working directory.

dmg macOS DMG Options

Name Description
background

The path to background image (default: build/background.tiff or build/background.png if exists). The resolution of this file determines the resolution of the installer window. If background is not specified, use window.size. Default locations expected background size to be 540x380.

See DMG with Retina background support.

backgroundColor The background color (accepts css colors). Defaults to #ffffff (white) if no background image.
icon The path to DMG icon (volume icon), which will be shown when mounted. Defaults to application icon (build/icon.icns).
iconSize The size of all the icons inside the DMG. Defaults to 80.
iconTextSize The size of all the icon texts inside the DMG. Defaults to 12.
title

The title of the produced DMG, which will be shown when mounted (volume name). Defaults to ${productName} ${version}

Macro ${productName}, ${version} and ${name} are supported.

contents The content — to customize icon locations.
format The disk image format, one of UDRW, UDRO, UDCO, UDZO, UDBZ, ULFO (lzfse-compressed image (OS X 10.11+ only)). Defaults to UDBZ (bzip2-compressed image).
window The DMG windows position and size. See dmg.window.

fileAssociations File Associations

macOS (corresponds to CFBundleDocumentTypes) and NSIS only. Array of option objects.

Name Description
ext The extension (minus the leading period). e.g. png.
name The name. e.g. PNG. Defaults to ext.
description windows-only. The description.
icon The path to icon (.icns for MacOS and .ico for Windows), relative to build (build resources directory). Defaults to ${firstExt}.icns/${firstExt}.ico (if several extensions specified, first is used) or to application icon.
role macOS-only The app’s role with respect to the type. The value can be Editor, Viewer, Shell, or None. Defaults to Editor. Corresponds to CFBundleTypeRole.
isPackage macOS-only Whether the document is distributed as a bundle. If set to true, the bundle directory is treated as a file. Corresponds to LSTypeIsPackage.

linux Linux Specific Options

Name Description
category The application category.
packageCategory The package category. Not applicable for AppImage.
description As description from application package.json, but allows you to specify different for Linux.
target

Target package type: list of AppImage, snap, deb, rpm, freebsd, pacman, p5p, apk, 7z, zip, tar.xz, tar.lz, tar.gz, tar.bz2, dir. Defaults to AppImage.

The most effective xz compression format used by default.

synopsis deb-only. The short description.
maintainer The maintainer. Defaults to author.
vendor The vendor. Defaults to author.
desktop The Desktop file entries (name to value).
compression deb-only. The compression type, one of gz, bzip2, xz. Defaults to xz.
depends Package dependencies. Defaults to ["gconf2", "gconf-service", "libnotify4", "libappindicator1", "libxtst6", "libnss3"] for deb.
executableName

The executable name. Defaults to productName.

Cannot be specified per target, allowed only in the linux.

mac macOS Specific Options

Name Description
category

The application category type, as shown in the Finder via View -> Arrange by Application Category when viewing the Applications directory.

For example, "category": "public.app-category.developer-tools" will set the application category to Developer Tools.

Valid values are listed in Apple’s documentation.

target The target package type: list of default, dmg, mas, pkg, 7z, zip, tar.xz, tar.lz, tar.gz, tar.bz2, dir. Defaults to default (dmg and zip for Squirrel.Mac).
identity

The name of certificate to use when signing. Consider using environment variables CSC_LINK or CSC_NAME instead of specifying this option. MAS installer identity is specified in the mas.

icon The path to application icon. Defaults to build/icon.icns (consider using this convention instead of complicating your configuration).
entitlements

The path to entitlements file for signing the app. build/entitlements.mac.plist will be used if exists (it is a recommended way to set). MAS entitlements is specified in the mas.

entitlementsInherit

The path to child entitlements which inherit the security settings for signing frameworks and bundles of a distribution. build/entitlements.mac.inherit.plist will be used if exists (it is a recommended way to set). Otherwise default.

This option only applies when signing with entitlements provided.

bundleVersion The CFBundleVersion. Do not use it unless you need to.
helperBundleId The bundle identifier to use in the application helper's plist. Defaults to ${appBundleIdentifier}.helper.

mas MAS (Mac Application Store) Specific Options

Name Description
entitlements

The path to entitlements file for signing the app. build/entitlements.mas.plist will be used if exists (it is a recommended way to set). Otherwise default.

entitlementsInherit

The path to child entitlements which inherit the security settings for signing frameworks and bundles of a distribution. build/entitlements.mas.inherit.plist will be used if exists (it is a recommended way to set). Otherwise default.

nsis

See NSIS target notes.

Name Description
oneClick One-click installation. Defaults to true.
perMachine

Defaults to false.

If oneClick is true (default): Install per all users (per-machine).

If oneClick is false: no install mode installer page (choice per-machine or per-user), always install per-machine.

allowElevation boring installer only. Allow requesting for elevation. If false, user will have to restart installer with elevated permissions. Defaults to true.
allowToChangeInstallationDirectory boring installer only. Whether to allow user to change installation directory. Defaults to false.
runAfterFinish one-click installer only. Run application after finish. Defaults to true.
guid See GUID vs Application Name.
installerIcon The path to installer icon. Defaults to build/installerIcon.ico or application icon.
installerHeader boring installer only. MUI_HEADERIMAGE, relative to the project directory. Defaults to build/installerHeader.bmp
installerHeaderIcon one-click installer only. The path to header icon (above the progress bar), relative to the project directory. Defaults to build/installerHeaderIcon.ico or application icon.
include The path to NSIS include script to customize installer. Defaults to build/installer.nsh. See Custom NSIS script.
script The path to NSIS script to customize installer. Defaults to build/installer.nsi. See Custom NSIS script.
license The path to EULA license file. Defaults to build/license.rtf or build/license.txt.
language * LCID Dec, defaults to 1033(English - United States).
warningsAsErrors Defaults to true. If warningsAsErrors is true (default): NSIS will treat warnings as errors. If warningsAsErrors is false: NSIS will allow warnings.
menuCategory Whether to create submenu for start menu shortcut and program files directory. Defaults to false. If true, company name will be used. Or string value.

protocols URL Protocol Schemes

Protocols to associate the app with. macOS only.

Please note — on macOS you need to register an open-url event handler.

Name Description
name The name. e.g. IRC server URL.
role macOS-only The app’s role with respect to the type. The value can be Editor, Viewer, Shell, or None. Defaults to Editor.
schemes The schemes. e.g. ["irc", "ircs"].

squirrelWindows

To use Squirrel.Windows please install electron-builder-squirrel-windows dependency.

Name Description
iconUrl

A URL to an ICO file to use as the application icon (displayed in Control Panel > Programs and Features). Defaults to the Electron icon.

Please note — local icon file url is not accepted, must be https/http.

loadingGif

The path to a .gif file to display during install. build/install-spinner.gif will be used if exists (it is a recommended way to set) (otherwise default).

msi Whether to create an MSI installer. Defaults to false (MSI is not created).
remoteReleases A URL to your existing updates. Or true to automatically set to your GitHub repository. If given, these will be downloaded to create delta updates.
remoteToken Authentication token for remote updates
useAppIdAsId Use appId to identify package instead of name.

win Windows Specific Options

Name Description
target

Target package type: list of nsis, appx, squirrel, 7z, zip, tar.xz, tar.lz, tar.gz, tar.bz2, dir. Defaults to nsis.

AppX package can be built only on Windows 10.

To use Squirrel.Windows please install electron-builder-squirrel-windows dependency.

signingHashAlgorithms

Array of signing algorithms used. Defaults to ['sha1', 'sha256']

For AppX sha256 is always used.

icon The path to application icon. Defaults to build/icon.ico (consider using this convention instead of complicating your configuration).
legalTrademarks The trademarks and registered trademarks.
certificateFile

The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable CSC_LINK (WIN_CSC_LINK) for some reason. Please see Code Signing.

certificatePassword

The password to the certificate provided in certificateFile. Please use it only if you cannot use env variable CSC_KEY_PASSWORD (WIN_CSC_KEY_PASSWORD) for some reason. Please see Code Signing.

certificateSubjectName The name of the subject of the signing certificate. Required only for EV Code Signing and works only on Windows.
rfc3161TimeStampServer The URL of the RFC 3161 time stamp server. Defaults to http://timestamp.comodoca.com/rfc3161.
timeStampServer The URL of the time stamp server. Defaults to http://timestamp.verisign.com/scripts/timstamp.dll.

dmg.window DMG Windows Position and Size

Name Description
x The X position relative to left of the screen. Defaults to 400.
y The Y position relative to top of the screen. Defaults to 100.
width * The width. Defaults to background image width or 540.
height * The height. Defaults to background image height or 380.

snap Snap Specific Options

Name Description
confinement The type of confinement supported by the snap. Can be either devmode (i.e. this snap doesn’t support running under confinement) or strict (i.e. full confinement supported via interfaces). Defaults to strict.
summary The 78 character long summary. Defaults to productName.
grade

The quality grade of the snap. It can be either devel (i.e. a development version of the snap, so not to be published to the “stable” or “candidate” channels) or “stable” (i.e. a stable release or release candidate, which can be released to all channels). Defaults to stable.

assumes The list of features that must be supported by the core in order for this snap to install.
stagePackages

The list of Ubuntu packages to use that are needed to support the app part creation. Like depends for deb. Defaults to ["libnotify4", "libappindicator1", "libxtst6", "libnss3", "libxss1", "fontconfig-config", "gconf2", "libasound2"].

ubuntuAppPlatformContent

Specify ubuntu-app-platform1 to use ubuntu-app-platform. Snap size will be greatly reduced, but it is not recommended for now because “the snaps must be connected before running uitk-gallery for the first time”.

appImage AppImage Specific Options

Name Description
includeRequiredLib Whether to include required system libraries (gconf2, libappindicator1). Defaults to false.

Fields in the package.json

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

Name Description
name The application name.
productName

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.

description The application description.
homepage

The url to the project homepage (NuGet Package projectUrl (optional) or Linux Package URL (required)).

If not specified and your project repository is public on GitHub, it will be https://github.com/${user}/${project} by default.

license linux-only. The license name.

File Patterns

files defaults to:

  • **/*
  • !**/node_modules/*/{CHANGELOG.md,README.md,README,readme.md,readme,test,__tests__,tests,powered-test,example,examples,*.d.ts}
  • !**/node_modules/.bin
  • !**/*.{o,hprof,orig,pyc,pyo,rbc}
  • !**/._*
  • !**/{.DS_Store,.git,.hg,.svn,CVS,RCS,SCCS,__pycache__,thumbs.db,.gitignore,.gitattributes,.editorconfig,.flowconfig,.yarn-metadata.json,.idea,appveyor.yml,.travis.yml,circle.yml,npm-debug.log,.nyc_output,yarn.lock,.yarn-integrity}

Hidden files are not ignored by default, but as you see, all files that should be ignored, are ignored by default.

Development dependencies are never copied in any case. You don't need to ignore it explicitly.

Multiple patterns are supported. You can use ${os} (expanded to mac, linux or win according to current platform) and ${arch} in the pattern. If directory matched, all contents are copied. So, you can just specify foo to copy foo directory.

Remember that default pattern **/* is not added to your custom if some of your patterns is not ignore (i.e. not starts with !). package.json 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).

Multiple Glob Patterns

 [
   // match all files
   "**/*",

   // except for js files in the foo/ directory
   "!foo/*.js",

   // unless it's foo/bar.js
   "foo/bar.js",
 ]

Excluding directories

Remember that !doNotCopyMe/**/* would match the files in the doNotCopyMe directory, but not the directory itself, so the empty directory would be created. Solution — use macro ${/*}, e.g. !doNotCopyMe${/*}.

Source and Destination Directories

You may also specify custom source and destination directories by using JSON objects instead of simple glob patterns. Note this only works for extraFiles and extraResources.

 [
   {
     "from": "path/to/source",
     "to": "path/to/destination",
     "filter": ["**/*", "!foo/*.js"]
   }
 ]

If from is given as a relative path, it is relative to the project directory. If to is given as a relative path, it is relative to the app's content directory for extraFiles and the app's resource directory for extraResources.

You can you ${os} and ${arch} in the from and to fields as well.

Build Version Management

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