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.

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

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. Note that you can only generate distributables for your current platform.

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 with --target=YourTarget.

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"] // An array of linux make targets
  },
  "electronPackagerConfig": {},
  "electronWinstallerConfig": {},
  "electronInstallerDMG": {},
  "electronInstallerFlatpak": {},
  "electronInstallerDebian": {},
  "electronInstallerRedhat": {}
}

Possible `make` targets

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

Configuring `package`

You can set electronPackagerConfig with any of the options from Electron Packager.

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.

Possible `publish` targets

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 repository `forge.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`
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.accessKey` - 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 to `forge.s3.folder` - The folder path to upload to inside your bucket, defaults to your application version `forge.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 slash `forge.electronReleaseServer.username` - The username for the admin panel on your server `forge.electronReleaseServer.password` - The password for the admin panel on your server

For example:

// github
{
  // Assume the GitHub repository is at https://github.com/username/repo
  "github_repository": {
    "owner": "username",
    "name": "repo"
  }
}

// s3
{
  "s3": {
    "accessKey": "<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"
  }
}

Custom `make` and `publish` targets

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} you can then just specify {name} as your make / publish target. The API for each is documented below.

API for `make` targets

You must export a Function that returns a Promise. Your function will be called with the following parameters.

appDir - The directory containing the packaged application
appName - The productName of the application
targetArch - The target architecture of the make command
forgeConfig - An object representing the users forgeConfig
packageJSON - An object representing the users package.json file

Your promise must resolve with an array of the artifacts you generated.

API for `publish` targets

You must export a Function that returns a Promise. Your function will be called with the following parameters.

artifactPaths - An array of absolute paths to artifacts to publish
packageJSON - An object representing the users package.json file
forgeConfig - An object representing the users forgeConfig
authToken - The value of --auth-token
tag - The value of --tag
platform - The platform you are publishing for
arch - The arch you are publishing for

You should use ora to indicate your publish progress.

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}"
}

mikebellcoder/electron-forge