Electron Forge
A complete tool for building modern Electron applications.
Electron Forge unifies the existing (and well maintained) build tools for Electron development into a simple, easy to use package so that anyone can jump right in to Electron development.
Website | Goals | Usage | Configuration | Support | Contributing | Changelog
Getting Started
Note: Electron Forge requires Node 6 or above, plus git installed.
npm install -g electron-forge
electron-forge init my-new-app
cd my-new-app
npm start
Alternatively, if you have a more recent version of npm
or yarn
, you can use
npx
,
or
yarn create
.
npx electron-forge init my-new-app
# or
yarn create electron-app my-new-app
# then
cd my-new-app
npm start
Project Goals
- Starting with Electron should be as simple as a single command.
- Developers shouldn't have to worry about
babel
,browserify
,webpack
, native module rebuilding, etc. Everything should "just work" for them out of the box. - Everything from creating the project to packaging the project for release should be handled by one dependency in a standard way while still offering users maximum choice and freedom.
With these goals in mind, under the hood this project uses, among others:
electron-compile
: a tool that lets you use modern and futuristic languages inside Electron without worrying about transpiling or build tooling.electron-rebuild
: Automatically recompiles native Node.js modules against the correct Electron version.- Electron Packager: Customizes and bundles your Electron app to get it ready for distribution.
Usage
Starting a new Project
npm install -g electron-forge
electron-forge init my-new-project
This command will generate a brand new project folder and install all your Node
module dependencies, so you will be all set to go. By default we will also
install the airbnb
linting modules. If you want to follow the standard
linting rules instead, use the --lintstyle=standard
argument.
You can also start a project with your
favorite framework with the --template
argument. E.g. --template=react
.
If you'd like to have pre-made configuration files for Travis CI and AppVeyor CI to automatically
build and deploy distributables to GitHub, use the --copy-ci-files
argument.
Importing an existing Project
electron-forge import existing-project-directory
Given an existing Electron project, this command will attempt to interactively navigate through the process of importing it to the Electron Forge format, so the commands listed below can be used. This includes being prompted to remove existing Electron build tools in favor of Electron Forge equivalents.
Launching your Project
electron-forge start
Any arguments after "start" will be passed through to your application when it's launched.
Packaging your Project
electron-forge package
Yes, it really is that simple. If you want to specify platform / arch, use the
--platform=<platform>
and --arch=<arch>
arguments.
Generating a distributable for your Project
electron-forge make
This will generate platform specific distributables (installers, distribution
packages, etc.) for you. By default, you can only generate distributables
for your current platform. If you want to specify platform / arch, use the
--platform=<platform>
and --arch=<arch>
arguments, but please note that
some distributables are not available to be built on anything but the platform
that is targeted. For example, appx
(Windows Store) distributables can only
be built on Windows.
Linting your Project
electron-forge lint
Publishing your Project
electron-forge publish
This will make
your project and publish any generated artifacts. By default it will publish to
GitHub, but you can change the publish target(s) with --target=YourTarget,YourTarget2
, where the
value is a comma-separated list of targets.
Config
Once you have generated a project, your package.json
file will have some
default forge
configuration. Below is the reference structure for this
config object:
{
"make_targets": {
"win32": ["squirrel"], // An array of win32 make targets
"darwin": ["zip", "dmg"], // An array of darwin make targets
"linux": ["deb", "rpm", "flatpak", "snap"] // An array of linux make targets
},
"electronPackagerConfig": {},
"electronRebuildConfig": {},
"electronWinstallerConfig": {},
"electronInstallerDMG": {},
"electronInstallerFlatpak": {},
"electronInstallerDebian": {},
"electronInstallerRedhat": {},
"electronInstallerSnap": {}
}
make
targets
Possible Target Name | Available Platforms | Description | Configurable Options | Default? | Requirements |
---|---|---|---|---|---|
zip |
All | Zips your packaged application | None | Yes | zip on Darwin/Linux |
squirrel |
Windows | Generates an installer and .nupkg files for Squirrel.Windows |
electronWinstallerConfig |
Yes | |
appx |
Windows | Generates a Windows Store package | windowsStoreConfig |
No | |
wix |
Windows | Generates a traditional MSI file | electronWixMSIConfig |
No | Wix Toolit |
dmg |
Darwin | Generates a DMG file | electronInstallerDMG |
No | |
deb |
Linux | Generates a Debian package | electronInstallerDebian |
Yes | fakeroot and dpkg |
rpm |
Linux | Generates an RPM package | electronInstallerRedhat |
Yes | rpm |
flatpak |
Linux | Generates a Flatpak file | electronInstallerFlatpak |
No | flatpak-builder |
snap |
Linux | Generates a Snap file | electronInstallerSnap |
No | snapcraft |
package
Configuring You can set electronPackagerConfig
with any of the options from
Electron Packager, except:
arch
(use the--arch
Forge command line argument instead, so it's available to all of Forge)asar.unpack
(useasar.unpackDir
instead)dir
(use thecwd
Forge command line argument instead, so it's available to all of Forge)electronVersion
(uses the exact version specified forelectron-prebuilt-compile
in yourdevDependencies
)out
platform
(use the--platform
Forge command line argument instead, so it's available to all of Forge)quiet
You can set electronRebuildConfig
with any of the options from
Electron Rebuild, except:
electronVersion
/--version
(uses the exact version specified forelectron-prebuilt-compile
in yourdevDependencies
)arch
/--arch
(use the--arch
Forge command line argument instead, so it's available to all of Forge)buildPath
/--module-dir
(uses your project'snode_modules
)
NOTE: You can also set your forge
config property of your package.json to point to a JS file that exports the config object:
{
...
"config": {
"forge": "./forge.config.js"
}
...
}
NOTE: If you use the JSON object then the afterCopy
and afterExtract
options are mapped to require
calls internally, so provide a path to a file that exports your hooks and they will still run. If you use
the JS file method mentioned above then you can use functions normally.
publish
targets
Possible Target Name | Description | Required Config |
---|---|---|
GitHub Releases - github |
Makes a new release for the current version (if required) and uploads the make artifacts as release assets | process.env.GITHUB_TOKEN - A personal access token with access to your releases forge.github_repository.owner - The owner of the GitHub repositoryforge.github_repository.name - The name of the GitHub repository forge.github_repository.draft - Create the release as a draft, defaults to true forge.github_repository.prerelease - Identify the release as a prerelease, defaults to false forge.github_repository.options - An Object of connection options, e.g., GitHub Enterprise settings or HTTP proxy URL |
Amazon S3 - s3 |
Uploads your artifacts to the given S3 bucket | process.env.ELECTRON_FORGE_S3_SECRET_ACCESS_KEY - Your secret access token for your AWS account (falls back to the standard AWS_SECRET_ACCESS_KEY environment variable)forge.s3.accessKeyId - Your access key for your AWS account (falls back to the standard AWS_ACCESS_KEY_ID environment variable)forge.s3.bucket - The name of the S3 bucket to upload toforge.s3.folder - The folder path to upload to inside your bucket, defaults to your application versionforge.s3.public - Whether to make the S3 upload public, defaults to false |
Electron Release Server - electron-release-server |
Makes a new release for the current version and uploads the artifacts to the correct platform/arch in the given version. If the version already exists no upload will be performed. The channel is determined from the current version. | forge.electronReleaseServer.baseUrl - The base URL of your release server, no trailing slashforge.electronReleaseServer.username - The username for the admin panel on your serverforge.electronReleaseServer.password - The password for the admin panel on your server |
Snapcraft - snapStore |
Uploads generated Snaps to the Snap Store. | forge.snapStore.release - If specified, a comma-separated list of channels to release to. |
For example:
// github
{
// Assume the GitHub repository is at https://github.com/username/repo
"github_repository": {
"owner": "username",
"name": "repo"
}
}
// s3
{
"s3": {
"accessKeyId": "<AWS_ACCESS_KEY>",
"bucket": "my_bucket_name",
"public": true
}
}
// Electron Release Server
{
"electronReleaseServer": {
"baseUrl": "https://update.mysite.com",
"username": "admin",
"password": "no_one_will_guess_this"
}
}
// Snap Store
{
"snapStore": {
"release": "candidate,beta"
}
}
make
and publish
targets
Custom You can make your own custom targets for the make
and publish
targets. If you publish them as
electron-forge-publisher-{name}
or electron-forge-maker-{name}
, they can be added to the app's
devDependencies
and can be specified as {name}
in the make / publish targets. Publicly published
third-party makers and
publishers are available in the NPM registry.
The API for each target type is documented below.
make
targets
API for You must export a Function that returns a Promise. Your function will be called with the following parameters.
appDir
- The directory containing the packaged applicationappName
- The productName of the applicationtargetArch
- The target architecture of the make commandforgeConfig
- An object representing the users forgeConfigpackageJSON
- An object representing the users package.json file
Your promise must resolve with an array of the artifacts you generated.
publish
targets
API for You must export a Function
that returns a Promise
. Your function will be called with the following keyword parameters:
dir
- The application directoryartifacts
- An array of absolute paths to artifacts to publishpackageJSON
- An object representing the user'spackage.json
fileforgeConfig
- An object representing the user'sforgeConfig
authToken
- The value of--auth-token
tag
- The value of--tag
platform
- The platform you are publishing forarch
- The arch you are publishing for
You should use ora
to indicate your publish progress.
Debugging your application on the command line
If you're using Electron 1.7 or later, you can specify the --inspect-electron
flag, which will
set the Electron --inspect
flag
with the default debugger port.
For example:
electron-forge start --inspect-electron
Debugging your application through VS Code
Debugging your Electron main process through VS Code is ridiculously easy with Forge. Simply add this as a launch config in VSCode and you're good to go.
{
"type": "node",
"request": "launch",
"name": "Electron Main",
"runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-forge-vscode-nix",
"windows": {
"runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-forge-vscode-win.cmd"
},
// runtimeArgs will be passed directly to your Electron application
"runtimeArgs": [
"foo",
"bar"
],
"cwd": "${workspaceRoot}"
}