Skip to content

Options

Jump to bottom Edit New page
develar edited this page Jun 15, 2016 · 77 revisions

Options

In the development package.json custom build field can be specified to customize format:

"build": {
  "osx": {
    "contents": [
      {
        "x": 410,
        "y": 220,
        "type": "link",
        "path": "/Applications"
      },
      {
        "x": 130,
        "y": 220,
        "type": "file",
        "path": "computed path to artifact, do not specify it - will be overwritten"
      }
    ]
  }
}

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

Here documented only electron-builder specific options:

Application 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.

Development package.json

Name Description
build See .build.
directories See .directories

.build

Name Description
appId

The application id. Used as CFBundleIdentifier for OS X and as Application User Model ID for Windows.

For windows only NSIS target supports it. Squirrel.Windows is not fixed yet.

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

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

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

Valid values are listed in Apple’s documentation.
asar

Whether to package the application’s source code into an archive, using Electron’s archive format. Defaults to true. Reasons why you may want to disable this feature are described in an application packaging tutorial in Electron’s documentation.

Or you can pass object of any asar options.
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. Defaults to **/* (i.e. hidden files 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 osx, 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, so, you have to add it explicitly — e.g. ["**/*", "!ignoreMe${/*}"].

May be specified in the platform options (e.g. in the build.osx).
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 OS X, 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 OS X, root directory for Linux/Windows).
osx See .build.osx.
mas See .build.mas.
win See .build.win.
nsis See .build.nsis.
linux See .build.linux.
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.

.build.osx

See all appdmg options.

Name Description
icon The path to DMG icon, which will be shown when mounted. Defaults to build/icon.icns.
background

The path to background (default: 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, see specification.
target Target package type: list of default, dmg, mas, 7z, zip, tar.xz, tar.lz, tar.gz, tar.bz2. 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. MAS installer identity is specified in the .build.mas.
entitlements

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

The path to child entitlements which inherit the security settings for signing frameworks and bundles of a distribution. build/entitlements.osx.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.

.build.mas

MAS (Mac Application Store) specific options (in addition to build.osx).

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.

.build.win

Name Description
target Target package type: list of squirrel, 7z, zip, tar.xz, tar.lz, tar.gz, tar.bz2. Defaults to squirrel.
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. If given, these will be downloaded to create delta updates.
remoteToken Authentication token for remote updates
signingHashAlgorithms Array of signing algorithms used. Defaults to ['sha1', 'sha256']

.build.nsis

NSIS target support in progress — not polished and not fully tested and checked.

See NSIS target notes.

Name Description
perMachine Mark "all users" (per-machine) as default. Not recommended. Defaults to false.
allowElevation Allow requesting for elevation. If false, user will have to restart installer with elevated permissions. Defaults to true.
oneClick One-click installation. Defaults to true.

.build.linux

Name Description
description As description from application package.json, but allows you to specify different for Linux.
synopsis deb-only. The short description.
maintainer The maintainer. Defaults to author.
vendor The vendor. Defaults to author.
compression deb-only. The compression type, one of gz, bzip2, xz. Defaults to xz.
depends Package dependencies. Defaults to ["libappindicator1", "libnotify-bin"].
target

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

The most effective xz compression format used by default.

Only deb is tested. Feel free to file issues for rpm and other package formats.

.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.

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${/*}.

Build Version Management

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

npm version donate

Want to contribute to this Wiki?

Edit /docs files and send a pull request.

Add a custom sidebar

Clone this wiki locally