electron-packager API

Short callback example:

const packager = require('electron-packager')
packager(options, function done_callback (err, appPaths) { /* … */ })

Short Promise example:

const packager = require('electron-packager')
packager(options)
  .then((appPaths) => { /* … */ })

`options`

Required

`dir`

String

The source directory.

Optional

All Platforms

`afterCopy`

Array of Functions

An array of functions to be called after your app directory has been copied to a temporary directory. Each function is called with five parameters:

buildPath (String): The path to the temporary folder where your app has been copied to
electronVersion (String): The version of electron you are packaging for
platform (String): The target platform you are packaging for
arch (String): The target architecture you are packaging for
callback (Function): Must be called once you have completed your actions

By default, the functions are called in parallel (via Promise.all). If you need the functions called serially, there is a utility function provided:

const packager = require('electron-packager')
const serialHooks = require('electron-packager/hooks').serialHooks

packager({
  // ...
  afterCopy: [serialHooks([
    (buildPath, electronVersion, platform, arch, callback) => {
      setTimeout(() => {
        console.log('first function')
        callback()
      }, 1000)
    },
    (buildPath, electronVersion, platform, arch, callback) => {
      console.log('second function')
      callback()
    }
  ])],
  // ...
})

`afterExtract`

Array of Functions

An array of functions to be called after Electron has been extracted to a temporary directory. Each function is called with five parameters:

buildPath (String): The path to the temporary folder where Electron has been extracted to
electronVersion (String): The version of electron you are packaging for
platform (String): The target platform you are packaging for
arch (String): The target architecture you are packaging for
callback (Function): Must be called once you have completed your actions

By default, the functions are called in parallel (via Promise.all). If you need the functions called serially, there is a utility function provided:

const packager = require('electron-packager')
const serialHooks = require('electron-packager/hooks').serialHooks

packager({
  // ...
  afterExtract: [serialHooks([
    (buildPath, electronVersion, platform, arch, callback) => {
      setTimeout(() => {
        console.log('first function')
        callback()
      }, 1000)
    },
    (buildPath, electronVersion, platform, arch, callback) => {
      console.log('second function')
      callback()
    }
  ])],
  // ...
})

`afterPrune`

Array of Functions

An array of functions to be called after the prune command has been run in the temporary directory. Each function is called with five parameters:

buildPath (String): The path to the temporary folder where your app has been copied to
electronVersion (String): The version of electron you are packaging for
platform (String): The target platform you are packaging for
arch (String): The target architecture you are packaging for
callback (Function): Must be called once you have completed your actions

NOTE: None of these functions will be called if the prune option is false.

By default, the functions are called in parallel (via Promise.all). If you need the functions called serially, there is a utility function provided:

const packager = require('electron-packager')
const serialHooks = require('electron-packager/hooks').serialHooks

packager({
  // ...
  afterPrune: [serialHooks([
    (buildPath, electronVersion, platform, arch, callback) => {
      setTimeout(() => {
        console.log('first function')
        callback()
      }, 1000)
    },
    (buildPath, electronVersion, platform, arch, callback) => {
      console.log('second function')
      callback()
    }
  ])],
  // ...
})

`all`

Boolean

When true, sets both arch and platform to all.

`appCopyright`

String

The human-readable copyright line for the app. Maps to the LegalCopyright metadata property on Windows, and NSHumanReadableCopyright on OS X.

`appVersion`

String

The release version of the application. By default the version property in the package.json is used but it can be overridden with this argument. If neither are provided, the version of Electron will be used. Maps to the ProductVersion metadata property on Windows, and CFBundleShortVersionString on OS X.

`arch`

String (default: the arch of the host computer running Node)

Allowed values: ia32, x64, armv7l, arm64 (Electron 1.8.0 and above), mips64el (Electron 1.8.2-beta.5 and above), all

The target system architecture(s) to build for. Not required if the all option is set. If arch is set to all, all supported architectures for the target platforms specified by platform will be built. Arbitrary combinations of individual architectures are also supported via a comma-delimited string or array of strings. The non-all values correspond to the architecture names used by Electron releases. This value is not restricted to the official set if download.mirror is set.

`asar`

Boolean or Object (default: false)

Whether to package the application's source code into an archive, using Electron's archive format. Reasons why you may want to enable this feature are described in an application packaging tutorial in Electron's documentation. When the value is true, pass default configuration to the asar module. The configuration values listed below can be customized when the value is an Object. Supported parameters include, but are not limited to:

ordering (String): A path to an ordering file for packing files. An explanation can be found on the Atom issue tracker.
unpack (String): A glob expression, when specified, unpacks the file with matching names to the app.asar.unpacked directory.
unpackDir (String): Unpacks the dir to the app.asar.unpacked directory whose names exactly or pattern match this string. The asar.unpackDir is relative to dir.

Some examples:

asar.unpackDir = 'sub_dir' will unpack the directory /<dir>/sub_dir
asar.unpackDir = '**/{sub_dir1/sub_sub_dir,sub_dir2}/*' will unpack the directories /<dir>/sub_dir1/sub_sub_dir and /<dir>/sub_dir2, but it will not include their subdirectories.
asar.unpackDir = '**/{sub_dir1/sub_sub_dir,sub_dir2}/**' will unpack the subdirectories of the directories /<dir>/sub_dir1/sub_sub_dir and /<dir>/sub_dir2.
asar.unpackDir = '**/{sub_dir1/sub_sub_dir,sub_dir2}/**/*' will unpack the directories /<dir>/sub_dir1/sub_sub_dir and /<dir>/sub_dir2 and their subdirectories.

`buildVersion`

String

The build version of the application. Defaults to the value of appVersion. Maps to the FileVersion metadata property on Windows, and CFBundleVersion on OS X.

`derefSymlinks`

Boolean (default: true)

Whether symlinks should be dereferenced during the copying of the application source.

`download`

Object

If present, passes custom options to electron-download (see the link for more detailed option descriptions and the defaults). Supported parameters include, but are not limited to:

cache (String): The directory where prebuilt, pre-packaged Electron downloads are cached.
mirror (String): The URL to override the default Electron download location.
quiet (Boolean - default: false): Whether to show a progress bar when downloading Electron.
strictSSL (Boolean - default: true): Whether SSL certificates are required to be valid when downloading Electron.

`electronVersion`

String

The Electron version with which the app is built (without the leading 'v') - for example, 1.4.13. See Electron releases for valid versions. If omitted, it will use the version of the nearest local installation of electron, electron-prebuilt-compile, or electron-prebuilt, defined in package.json in either dependencies or devDependencies.

`extraResource`

String or Array of *String*s

One or more files to be copied directly into the app's Contents/Resources directory for OS X target platforms, and the resources directory for other target platforms.

`executableName`

String

The name of the executable file (sans file extension). Defaults to the value for the name parameter. For darwin or mas target platforms, this does not affect the name of the .app folder - this will use name parameter.

`icon`

String

The local path to the icon file, if the target platform supports setting embedding an icon.

Currently you must look for conversion tools in order to supply an icon in the format required by the platform:

OS X: .icns
Windows: .ico (See the readme for details on non-Windows platforms)
Linux: this option is not required, as the dock/window list icon is set via the icon option in the BrowserWindow constructor. Please note that you need to use a PNG, and not the OS X or Windows icon formats, in order for it to show up in the dock/window list. Setting the icon in the file manager is not currently supported.

If the file extension is omitted, it is auto-completed to the correct extension based on the platform, including when --platform=all is in effect.

`ignore`

RegExp, Array of *RegExp*s, or Function

One or more additional regular expression patterns which specify which files to ignore when copying files to create the app bundle(s). The regular expressions are matched against the absolute path of a given file/directory to be copied.

The following paths are always ignored (when you aren't using the predicate function that is described after the list):

the directory specified by the out parameter
the temporary directory used to build the Electron app
node_modules/.bin
node_modules/electron
node_modules/electron-prebuilt
node_modules/electron-prebuilt-compile
node_modules/electron-packager
.git
files and folders ending in .o and .obj

Please note that glob patterns will not work.

Note: If you're trying to ignore Node modules specified in devDependencies, you may want to use prune instead.

Alternatively, this can be a predicate function that, given an absolute file path, returns true if the file should be ignored, or false if the file should be kept. This does not use any of the default ignored directories listed above.

`name`

String

The application name. If omitted, it will use the productName or name value from the nearest package.json.

Regardless of source, characters in the Electron app name which are not allowed in all target platforms' filenames (e.g., /), will be replaced by hyphens (-).

`out`

String (default: current working directory)

The base directory where the finished package(s) are created.

`overwrite`

Boolean (default: false)

Whether to replace an already existing output directory for a given platform (true) or skip recreating it (false).

`platform`

String (default: the arch of the host computer running Node)

Allowed values: linux, win32, darwin, mas, all

The target platform(s) to build for. Not required if the all option is set. If platform is set to all, all supported target platforms for the target architectures specified by arch will be built. Arbitrary combinations of individual platforms are also supported via a comma-delimited string or array of strings. The non-all values correspond to the platform names used by Electron releases. This value is not restricted to the official set if download.mirror is set.

`prune`

Boolean (default: true)

Walks the node_modules dependency tree to remove all of the packages specified in the devDependencies section of package.json from the outputted Electron app.

`quiet`

Boolean (default: false)

If true, disables printing informational and warning messages to the console when packaging the application. This does not disable errors.

`tmpdir`

String or false (default: system temp directory)

The base directory to use as a temp directory. Set to false to disable use of a temporary directory.

OS X/Mac App Store targets only

`appBundleId`

String

The bundle identifier to use in the application's plist.

`appCategoryType`

String

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.

`extendInfo`

String or Object

When the value is a String, the filename of a plist file. Its contents are added to the app's plist. When the value is an Object, an already-parsed plist data structure that is merged into the app's plist.

Entries from extend-info override entries in the base plist file supplied by electron, electron-prebuilt-compile, or electron-prebuilt, but are overridden by other explicit arguments such as appVersion or appBundleId.

`helperBundleId`

String

The bundle identifier to use in the application helper's plist.

`osxSign`

Object or true

If present, signs OS X target apps when the host platform is OS X and XCode is installed. When the value is true, pass default configuration to the signing module. The configuration values listed below can be customized when the value is an Object. See electron-osx-sign for more detailed option descriptions and the defaults.

identity (String): The identity used when signing the package via codesign.
entitlements (String): The path to the 'parent' entitlements.
entitlements-inherit (String): The path to the 'child' entitlements.

`protocols`

Array of *Object*s

One or more URL protocols associated with the Electron app.

Each Object is required to have the following properties:

name (String): The descriptive name. Maps to the CFBundleURLName metadata property.
schemes (Array of *String*s): One or more protocol schemes associated with the app. For example, specifying myapp would cause URLs such as myapp://path to be opened with the app. Maps to the CFBundleURLSchemes metadata property.

Windows targets only

`win32metadata`

Object

Object (also known as a "hash") of application metadata to embed into the executable:

CompanyName (defaults to author name from the nearest package.json)
FileDescription (defaults to either productName or name from the nearest package.json)
OriginalFilename (defaults to renamed .exe file)
ProductName (defaults to either productName or name from the nearest package.json)
InternalName (defaults to either productName or name from the nearest package.json)
requested-execution-level
application-manifest

For more information, see the node-rcedit module.

callback

`err`

Error (or Array, in the case of an copy error)

Contains errors, if any.

`appPaths`

Array of *String*s

Paths to the newly created application bundles.

api.md 17 KB Permalink History Raw

electron-packager API

options

Required

dir

Optional

All Platforms

afterCopy

afterExtract

afterPrune

all

appCopyright

appVersion

arch

asar

buildVersion

derefSymlinks

download

electronVersion

extraResource

executableName

icon

ignore

name

out

overwrite

platform

prune

quiet

tmpdir

OS X/Mac App Store targets only

appBundleId

appCategoryType

extendInfo

helperBundleId

osxSign

protocols

Windows targets only

win32metadata

callback

err

appPaths

api.md 17 KB

Permalink History Raw

`options`

`dir`

`afterCopy`

`afterExtract`

`afterPrune`

`all`

`appCopyright`

`appVersion`

`arch`

`asar`

`buildVersion`

`derefSymlinks`

`download`

`electronVersion`

`extraResource`

`executableName`

`icon`

`ignore`

`name`

`out`

`overwrite`

`platform`

`prune`

`quiet`

`tmpdir`

`appBundleId`

`appCategoryType`

`extendInfo`

`helperBundleId`

`osxSign`

`protocols`

`win32metadata`

`err`

`appPaths`