Interface Options

Options passed to the packager() function.

interface Options {
    afterAsar?: HookFunction[];
    afterComplete?: HookFunction[];
    afterCopy?: HookFunction[];
    afterCopyExtraResources?: HookFunction[];
    afterExtract?: HookFunction[];
    afterFinalizePackageTargets?: FinalizePackageTargetsHookFunction[];
    afterInitialize?: HookFunction[];
    afterPrune?: HookFunction[];
    all?: boolean;
    appBundleId?: string;
    appCategoryType?: string;
    appCopyright?: string;
    appVersion?: string;
    arch?: string | string[];
    asar?: boolean | CreateOptions;
    beforeAsar?: HookFunction[];
    beforeCopy?: HookFunction[];
    beforeCopyExtraResources?: HookFunction[];
    buildVersion?: string;
    darwinDarkModeSupport?: boolean;
    derefSymlinks?: boolean;
    dir: string;
    download?: ElectronDownloadRequestOptions;
    electronVersion?: string;
    electronZipDir?: string;
    executableName?: string;
    extendHelperInfo?: string | {
        [property: string]: any;
    };
    extendInfo?: string | {
        [property: string]: any;
    };
    extraResource?: string | string[];
    helperBundleId?: string;
    icon?: string;
    ignore?: RegExp | (string | RegExp)[] | IgnoreFunction;
    junk?: boolean;
    name?: string;
    osxNotarize?: NotaryToolCredentials;
    osxSign?: true | OsxSignOptions;
    osxUniversal?: OsxUniversalOptions;
    out?: string;
    overwrite?: boolean;
    platform?: string | string[];
    prebuiltAsar?: string;
    protocols?: MacOSProtocol[];
    prune?: boolean;
    quiet?: boolean;
    tmpdir?: string | false;
    usageDescription?: {
        [property: string]: string;
    };
    win32metadata?: Win32MetadataOptions;
    windowsSign?: true | WindowsSignOptions;
}

Hierarchy (view full)

Other

afterAsar?: HookFunction[]

Functions to be called after your app directory has been packaged into an .asar file.

Note: afterAsar will only be called if the asar option is set.

afterComplete?: HookFunction[]

Functions to be called after the packaged application has been moved to the final directory.

afterCopy?: HookFunction[]

Functions to be called after your app directory has been copied to a temporary directory.

Note: afterCopy will not be called if the prebuiltAsar option is set.

afterCopyExtraResources?: HookFunction[]

Functions to be called after the files specified in the extraResource option have been copied.

afterExtract?: HookFunction[]

Functions to be called after the prebuilt Electron binary has been extracted to a temporary directory.

afterFinalizePackageTargets?: FinalizePackageTargetsHookFunction[]

Functions to be called after the final matrix of platform/arch combination is determined. Use this to learn what archs/platforms packager is targetting when you pass "all" as a value.

afterInitialize?: HookFunction[]
afterPrune?: HookFunction[]

Functions to be called after Node module pruning has been applied to the application.

Note: None of these functions will be called if the prune option is false or the prebuiltAsar option is set.

all?: boolean

When true, sets both arch and platform to all.

appBundleId?: string
appCopyright?: string

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

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

arch?: string | string[]

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|download.mirrorOptions]] is set.

Defaults to the arch of the host computer running Electron Packager.

Arch values for the official prebuilt Electron binaries:

  • ia32
  • x64
  • armv7l
  • arm64 (Linux: Electron 1.8.0 and above; Windows: 6.0.8 and above; macOS: 11.0.0-beta.1 and above)
  • mips64el (Electron 1.8.2-beta.5 to 1.8.8)
asar?: boolean | CreateOptions

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 include mitigating issues around long path names on Windows, slightly speeding up require, and concealing your source code from cursory inspection. When the value is true, it passes the default configuration to the asar module. The configuration values can be customized when the value is an Object. Supported sub-options 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.

Defaults to false.

Some examples:

  • asar.unpackDir = 'sub_dir' will unpack the directory /<dir>/sub_dir
  • asar.unpackDir = path.join('**', '{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 = path.join('**', '{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 = path.join('**', '{sub_dir1/sub_sub_dir,sub_dir2}', '**', '*') will unpack the directories /<dir>/sub_dir1/sub_sub_dir and /<dir>/sub_dir2 and their subdirectories.

Note: asar will have no effect if the prebuiltAsar option is set.

beforeAsar?: HookFunction[]

Functions to be called before your app directory is packaged into an .asar file.

Note: beforeAsar will only be called if the asar option is set.

beforeCopy?: HookFunction[]

Functions to be called before your app directory is copied to a temporary directory.

Note: beforeCopy will not be called if the prebuiltAsar option is set.

beforeCopyExtraResources?: HookFunction[]

Functions to be called before the files specified in the extraResource option are copied.

buildVersion?: string

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

derefSymlinks?: boolean

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

Note: derefSymlinks will have no effect if the prebuiltAsar option is set.

dir: string

The source directory.

download?: ElectronDownloadRequestOptions

If present, passes custom options to @electron/get. See the module for option descriptions, proxy support, and defaults. Supported parameters include, but are not limited to:

  • cacheRoot (string): The directory where prebuilt, pre-packaged Electron downloads are cached.
  • mirrorOptions (Object): Options to override the default Electron download location.

Note: download sub-options will have no effect if the electronZipDir option is set.

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 or electron-nightly
  • defined in package.json in either devDependencies or dependencies.
electronZipDir?: string

The local path to a directory containing Electron ZIP files for Electron Packager to unzip, instead of downloading them. The ZIP filenames should be in the same format as the ones downloaded from the Electron releases site.

Note: Setting this option prevents the download sub-options from being used, as the functionality gets skipped over.

executableName?: string

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

extraResource?: string | string[]

One or more files to be copied directly into the app's Contents/Resources directory for macOS target platforms, and the resources directory for other target platforms. The resources directory can be referenced in the packaged app via the process.resourcesPath value.

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:

  • macOS: .icns
  • Windows: .ico (See the readme for details on non-Windows platforms)
  • Linux: this option is not supported, 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 macOS 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|platform: 'all']] is in effect.

ignore?: RegExp | (string | RegExp)[] | IgnoreFunction

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.

Please note that glob patterns will not work.

The following paths are always ignored (when you aren't using an IgnoreFunction):

  • the directory specified by the out option
  • the temporary directory used to build the Electron app
  • node_modules/.bin
  • node_modules/electron
      • node_modules/electron-nightly
  • .git
  • files and folders ending in .o and .obj

Note: Node modules specified in devDependencies are ignored by default, via the prune option.

Note: ignore will have no effect if the prebuiltAsar option is set.

junk?: boolean

Ignores system junk files when copying the Electron app, regardless of the ignore option.

Note: junk will have no effect if the prebuiltAsar option is set.

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

osxUniversal?: OsxUniversalOptions

Used to provide custom options to the internal call to @electron/universal when building a macOS app with the target architecture of "universal". Unused otherwise, providing a value does not imply a universal app is built.

out?: string

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

Defaults to the current working directory.

overwrite?: boolean

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

platform?: string | string[]

The target platform(s) to build for.

Not required if the all option is set. If platform is set to all, all officially supported target platforms for the target architectures specified by the arch option will be built. Arbitrary combinations of individual platforms are also supported via a comma-delimited string or array of strings.

The official non-all values correspond to the platform names used by Electron releases. This value is not restricted to the official set if [[download|`download.mirrorOptions]] is set.

Defaults to the platform of the host computer running Electron Packager.

Platform values for the official prebuilt Electron binaries:

  • darwin (macOS)
  • linux
  • mas (macOS, specifically for submitting to the Mac App Store)
  • win32
prebuiltAsar?: string

The path to a prebuilt ASAR file.

Note: Setting this option prevents the following options from being used, as the functionality gets skipped over:

prune?: boolean

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.

Defaults to true.

Note: prune will have no effect if the prebuiltAsar option is set.

quiet?: boolean

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

Defaults to false.

tmpdir?: string | false

The base directory to use as a temporary directory. Set to false to disable use of a temporary directory. Defaults to the system's temporary directory.

Windows

win32metadata?: Win32MetadataOptions

Application metadata to embed into the Windows executable.

windowsSign?: true | WindowsSignOptions

If present, signs Windows binary files. When the value is true, pass default configuration to the signing module. See @electron/windows-sign for sub-option descriptions and their defaults.

macOS

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.

darwinDarkModeSupport?: boolean

Forces support for Mojave (macOS 10.14) dark mode in your packaged app. This sets the NSRequiresAquaSystemAppearance key to false in your app's Info.plist. For more information, see the Electron documentation and the Apple developer documentation.

extendHelperInfo?: string | {
    [property: string]: any;
}

When the value is a string, specifies the filename of a plist file. Its contents are merged into all the Helper apps' Info.plist files. When the value is an Object, it specifies an already-parsed plist data structure that is merged into all the Helper apps' Info.plist files.

Entries from extendHelperInfo override entries in the helper apps' Info.plist file supplied by

Type declaration

  • [property: string]: any
extendInfo?: string | {
    [property: string]: any;
}

When the value is a string, specifies the filename of a plist file. Its contents are merged into the app's Info.plist. When the value is an Object, it specifies an already-parsed plist data structure that is merged into the app's Info.plist.

Entries from extendInfo override entries in the base Info.plist file supplied by

Type declaration

  • [property: string]: any
helperBundleId?: string

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

osxNotarize?: NotaryToolCredentials

If present, notarizes macOS target apps when the host platform is macOS and Xcode is installed. See @electron/notarize for option descriptions, such as how to use appleIdPassword safely or obtain an API key.

Requires the osxSign option to be set.

osxSign?: true | OsxSignOptions

If present, signs macOS target apps when the host platform is macOS and Xcode is installed. When the value is true, pass default configuration to the signing module. See @electron/osx-sign for sub-option descriptions and their defaults. Options include, but are not limited to:

  • identity (string): The identity used when signing the package via codesign.
  • binaries (array): Path to additional binaries that will be signed along with built-ins of Electron/
protocols?: MacOSProtocol[]

The URL protocol schemes associated with the Electron app.

usageDescription?: {
    [property: string]: string;
}

Human-readable descriptions of how the Electron app uses certain macOS features. These are displayed in the App Store. A non-exhaustive list of available properties:

  • Camera - required for media access API usage in macOS Catalina
  • Microphone - required for media access API usage in macOS Catalina

Valid properties are the Cocoa keys for MacOS of the pattern NS(.*)UsageDescription, where the captured group is the key to use.

Example:

{
usageDescription: {
Camera: 'Needed for video calls',
Microphone: 'Needed for voice calls'
}
}

Type declaration

  • [property: string]: string