Customize and package your Electron app with OS-specific bundles (.app, .exe, etc.) via JS or CLI
JavaScript Shell
Latest commit cff9713 May 18, 2018
Permalink
Failed to load latest commit information.
.github Add config for probot's no-response bot Nov 4, 2017
docs Deprecate the callback version of the packager API (#837) May 3, 2018
test Better detection of node modules when pruning May 18, 2018
.eslintignore 'use strict' in all of the files (#351) May 25, 2016
.gitignore Convert testsuite to AVA Dec 27, 2017
.travis.yml Use codecov instead of coveralls Jan 28, 2018
CODE_OF_CONDUCT.md Add explicit files for SUPPORT and CODE_OF_CONDUCT Jul 30, 2017
CONTRIBUTING.md Update Standard JS URL Oct 23, 2017
LICENSE rename maxogden -> electron-userland Feb 27, 2016
NEWS.md 12.1.0 May 19, 2018
SUPPORT.md Add initial FAQ Sep 16, 2017
cli.js Add --version to print out Packager/Node versions, target platform/arch May 13, 2018
collaborators.md add @jlord to collaborators Feb 18, 2016
common.js Add --version to print out Packager/Node versions, target platform/arch May 13, 2018
download.js Move download-related code to its own file Jan 15, 2018
hooks.js Add a utility function to execute hooks serially Mar 20, 2018
ignore.js Refactor pruning to be part of the copy filter Mar 27, 2018
index.js Add --version to print out Packager/Node versions, target platform/arch May 13, 2018
infer.js getPackageInfo doesn't need to be promisified May 8, 2018
linux.js Add common function to ensure certain values are Arrays Jan 15, 2018
mac.js Add support for customizing the login helper on MAS Feb 25, 2018
package.json 12.1.0 May 19, 2018
platform.js Refactor default_app removal code Apr 10, 2018
prune.js Better detection of node modules when pruning May 18, 2018
readme.md Add docs for mips64el support Feb 7, 2018
targets.js Prevent trying to download mips64el arch for Electron 2.x May 14, 2018
usage.txt Add --version to print out Packager/Node versions, target platform/arch May 13, 2018
win32.js Add common function to ensure certain values are Arrays Jan 15, 2018

readme.md

Electron Packager

Package your Electron app into OS-specific bundles (.app, .exe, etc.) via JavaScript or the command line.

Travis CI Build Status AppVeyor Build status Coverage Status Dependency Status

Supported Platforms | Installation | Usage | API | Contributing | Support | Related Apps/Libraries | FAQ | Release Notes


About

Electron Packager is a command line tool and Node.js library that bundles Electron-based application source code with a renamed Electron executable and supporting files into folders ready for distribution.

For creating distributables like installers and Linux packages, consider using either Electron Forge (which uses Electron Packager internally), or one of the related Electron tools, which utilizes Electron Packager-created folders as a basis.

Note that packaged Electron applications can be relatively large. A zipped, minimal Electron application is approximately the same size as the zipped prebuilt binary for a given target platform, target arch, and Electron version (files named electron-v${version}-${platform}-${arch}.zip).

Electron Packager is an OPEN Open Source Project

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See CONTRIBUTING.md and openopensource.org for more details.

Supported Platforms

Electron Packager is known to run on the following host platforms:

  • Windows (32/64 bit)
  • OS X (also known as macOS)
  • Linux (x86/x86_64)

It generates executables/bundles for the following target platforms:

  • Windows (also known as win32, for both 32/64 bit)
  • OS X (also known as darwin) / Mac App Store (also known as mas)*
  • Linux (for x86, x86_64, armv7l, arm64, and mips64el architectures)

* Note for OS X / MAS target bundles: the .app bundle can only be signed when building on a host OS X platform.

Installation

This module requires Node.js 4.0 or higher to run.

# for use in npm scripts
npm install electron-packager --save-dev

# for use from cli
npm install electron-packager -g

Building Windows apps from non-Windows platforms

Building an Electron app for the Windows target platform requires editing the Electron.exe file. Currently, Electron Packager uses node-rcedit to accomplish this. A Windows executable is bundled in that Node package and needs to be run in order for this functionality to work, so on non-Windows host platforms, Wine 1.6 or later needs to be installed. On OS X, it is installable via Homebrew.

Usage

JavaScript API usage can be found in the API documentation.

From the Command Line

Running electron-packager from the command line has this basic form:

electron-packager <sourcedir> <appname> --platform=<platform> --arch=<arch> [optional flags...]

This will:

  • Find or download the correct release of Electron
  • Use that version of Electron to create a app in <out>/<appname>-<platform>-<arch> (this can be customized via an optional flag)

--platform and --arch can be omitted, in two cases:

  • If you specify --all instead, bundles for all valid combinations of target platforms/architectures will be created.
  • Otherwise, a single bundle for the host platform/architecture will be created.

For an overview of the other optional flags, run electron-packager --help or see usage.txt. For detailed descriptions, see the API documentation.

If appname is omitted, this will use the name specified by "productName" or "name" in the nearest package.json.

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

You should be able to launch the app on the platform you built for. If not, check your settings and try again.

Be careful not to include node_modules you don't want into your final app. If you put them in the devDependencies section of package.json, by default none of the modules related to those dependencies will be copied in the app bundles. (This behavior can be turned off with the --no-prune flag.) In addition, folders like .git and node_modules/.bin will be ignored by default. You can use --ignore to ignore files and folders via a regular expression (not a glob pattern). Examples include --ignore=\.gitignore or --ignore="\.git(ignore|modules)".

Example

Let's assume that you have made an app based on the electron-quick-start repository on a OS X host platform with the following file structure:

foobar
├── package.json
├── index.html
├── […other files, like LICENSE…]
└── script.js

…and that the following is true:

  • electron-packager is installed globally
  • productName in package.json has been set to Foo Bar
  • The electron module is in the devDependencies section of package.json, and set to the exact version of 1.4.15.
  • npm install for the Foo Bar app has been run at least once

When one runs the following command for the first time in the foobar directory:

electron-packager .

electron-packager will do the following:

  • Use the current directory for the sourcedir
  • Infer the appname from the productName in package.json
  • Infer the appVersion from the version in package.json
  • Infer the platform and arch from the host, in this example, darwin platform and x64 arch.
  • Download the darwin x64 build of Electron 1.4.15 (and cache the downloads in ~/.electron)
  • Build the OS X Foo Bar.app
  • Place Foo Bar.app in foobar/Foo Bar-darwin-x64/ (since an out directory was not specified, it used the current working directory)

The file structure now looks like:

foobar
├── Foo Bar-darwin-x64
│   ├── Foo Bar.app
│   │   └── […Mac app contents…]
│   ├── LICENSE
│   └── version
├── […other application bundles, like "Foo Bar-win32-x64" (sans quotes)…]
├── package.json
├── index.html
├── […other files, like LICENSE…]
└── script.js

The Foo Bar.app folder generated can be executed by a system running OS X, which will start the packaged Electron app. This is also true of the Windows x64 build on a system running a new enough version of Windows for a 64-bit system (via Foo Bar-win32-x64/Foo Bar.exe), and so on.

Related

Distributable Creators

Windows:

OS X:

Linux:

Plugins

These Node modules utilize Electron Packager API hooks: