:electron: A complete tool for building and publishing Electron applications
Перейти к файлу
Samuel Attard e37f761411
updated CHANGELOG.md
2016-12-30 14:12:00 +13:00
ci chore(tests): run flatpak runtime install in local Dockerfile 2016-12-25 19:57:45 -08:00
src refactor(publisher): move github publish logic to own file 2016-12-30 14:11:09 +13:00
test test(generic): add tests for the require-search util 2016-12-30 14:11:09 +13:00
tmpl feat(publisher): initial work on a publish command to sent make artifacts to github 2016-12-30 14:11:09 +13:00
.appveyor.yml chore(tests): add AppVeyor support (#15) 2016-12-12 02:44:12 +11:00
.cz.js chore(generic): add publisher to cz config 2016-12-30 14:11:09 +13:00
.eslintignore Add tests 2016-10-06 01:50:40 +11:00
.eslintrc fix(maker): move electron-installer-debian to optional deps so that installs work on windows 2016-12-04 17:20:50 +11:00
.gitignore Add tests 2016-10-06 01:50:40 +11:00
.npmignore feat(maker): add the flatpak maker for the linux target 2016-12-08 20:57:52 -08:00
.travis.yml chore(tests): disable building branches on Travis CI 2016-12-10 21:34:40 -08:00
CHANGELOG.md updated CHANGELOG.md 2016-12-30 14:12:00 +13:00
CONTRIBUTING.md chore(generic): rename all instances of marshallofsound to electron-userland 2016-12-11 20:21:10 +11:00
LICENSE docs(LICENSE): add a license file 2016-12-03 23:55:46 +11:00
README.md docs(publisher): document the API for custom makers and publishers 2016-12-30 14:11:09 +13:00
gulpfile.babel.js feat(generic): map the alias bin commands to the correct commander files 2016-12-29 15:45:44 +13:00
issue_template.md docs(generic): add contributing/issue/pull request docs + news 2016-12-10 20:56:13 -08:00
package.json feat(publisher): initial work on a publish command to sent make artifacts to github 2016-12-30 14:11:09 +13:00
pull_request_template.md chore(generic): rename all instances of marshallofsound to electron-userland 2016-12-11 20:21:10 +11:00

README.md

Electron Forge

Linux/macOS Build Status Windows Build status Commitizen friendly npm version npm license status

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

  1. Starting with Electron should be as simple as a single command.
  2. Developers shouldn't have to worry about babel, browserify, webpack, etc. Everything should "just work" for them out of the box.
  3. 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 electron-compile: a tool that lets you use modern and futuristic languages inside Electron without worrying about transpiling or build tooling.

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

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

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

You should use ora to indicate your publish progress.