1 | Electron Forge
|
2 | --------------
|
3 | [![Linux/macOS Build Status](https://travis-ci.org/electron-userland/electron-forge.svg?branch=master)](https://travis-ci.org/electron-userland/electron-forge)
|
4 | [![Windows Build status](https://ci.appveyor.com/api/projects/status/79ae80nek1eucyy3?svg=true)](https://ci.appveyor.com/project/electron-userland/electron-forge)
|
5 | [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
|
6 | [![npm version](https://badge.fury.io/js/electron-forge.svg)](https://www.npmjs.com/package/electron-forge)
|
7 | [![npm](https://img.shields.io/npm/dt/electron-forge.svg?maxAge=2592000)](https://www.npmjs.com/package/electron-forge)
|
8 | [![license](https://img.shields.io/github/license/electron-userland/electron-forge.svg)](https://github.com/electron-userland/electron-forge/blob/master/LICENSE)
|
9 | ![status](https://img.shields.io/badge/Status-%20Ready%20for%20Awesome-red.svg)
|
10 |
|
11 | A complete tool for building modern Electron applications.
|
12 |
|
13 | Electron Forge unifies the existing (and well maintained) build tools for
|
14 | Electron development into a simple, easy to use package so that anyone can
|
15 | jump right in to Electron development.
|
16 |
|
17 | # Getting Started
|
18 |
|
19 | **Note**: Electron Forge requires Node 6 or above, plus git installed.
|
20 |
|
21 | ```bash
|
22 | npm install -g electron-forge
|
23 | electron-forge init my-new-app
|
24 | cd my-new-app
|
25 | npm start
|
26 | ```
|
27 |
|
28 | Alternatively, if you have a more recent version of `npm` or `yarn`, you can use
|
29 | [`npx`](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b),
|
30 | or
|
31 | [`yarn create`](https://yarnpkg.com/blog/2017/05/12/introducing-yarn/).
|
32 |
|
33 | ```bash
|
34 | npx electron-forge init my-new-app
|
35 | # or
|
36 | yarn create electron-app my-new-app
|
37 |
|
38 | # then
|
39 | cd my-new-app
|
40 | npm start
|
41 | ```
|
42 |
|
43 | # Project Goals
|
44 |
|
45 | 1. Starting with Electron should be as simple as a single command.
|
46 | 2. Developers shouldn't have to worry about `babel`, `browserify`, `webpack`,
|
47 | native module rebuilding, etc. Everything should "just work" for them out
|
48 | of the box.
|
49 | 3. Everything from creating the project to packaging the project for release
|
50 | should be handled by one dependency in a standard way while still offering
|
51 | users maximum choice and freedom.
|
52 |
|
53 | With these goals in mind, under the hood this project uses, among others:
|
54 |
|
55 | * [`electron-compile`](https://github.com/electron/electron-compile): a tool
|
56 | that lets you use modern and futuristic languages inside Electron without
|
57 | worrying about transpiling or build tooling.
|
58 | * [`electron-rebuild`](https://github.com/electron/electron-rebuild):
|
59 | Automatically recompiles native Node.js modules against the correct
|
60 | Electron version.
|
61 | * [Electron Packager](https://github.com/electron-userland/electron-packager):
|
62 | Customizes and bundles your Electron app to get it ready for distribution.
|
63 |
|
64 | # Usage
|
65 |
|
66 | ## Starting a new Project
|
67 |
|
68 | ```bash
|
69 | npm install -g electron-forge
|
70 | electron-forge init my-new-project
|
71 | ```
|
72 |
|
73 | This command will generate a brand new project folder and install all your Node
|
74 | module dependencies, so you will be all set to go. By default we will also
|
75 | install the `airbnb` linting modules. If you want to follow the `standard`
|
76 | linting rules instead, use the `--lintstyle=standard` argument.
|
77 |
|
78 | You can also start a project with your
|
79 | [favorite framework](https://electronforge.io/templates) with the `--template`
|
80 | argument. E.g. `--template=react`.
|
81 |
|
82 | If you'd like to have pre-made configuration files for Travis CI and AppVeyor CI to automatically
|
83 | build and deploy distributables to GitHub, use the `--copy-ci-files` argument.
|
84 |
|
85 | ## Importing an existing Project
|
86 |
|
87 | ```bash
|
88 | electron-forge import existing-project-directory
|
89 | ```
|
90 |
|
91 | Given an existing Electron project, this command will attempt to interactively
|
92 | navigate through the process of importing it to the Electron Forge format, so
|
93 | the commands listed below can be used. This includes being prompted to remove
|
94 | existing Electron build tools in favor of Electron Forge equivalents.
|
95 |
|
96 | ## Launching your Project
|
97 |
|
98 | ```bash
|
99 | electron-forge start
|
100 | ```
|
101 |
|
102 | Any arguments after "start" will be passed through to your application when
|
103 | it's launched.
|
104 |
|
105 | ## Packaging your Project
|
106 |
|
107 | ```bash
|
108 | electron-forge package
|
109 | ```
|
110 |
|
111 | Yes, it really is that simple. If you want to specify platform / arch, use the
|
112 | `--platform=<platform>` and `--arch=<arch>` arguments.
|
113 |
|
114 | ## Generating a distributable for your Project
|
115 |
|
116 | ```bash
|
117 | electron-forge make
|
118 | ```
|
119 |
|
120 | This will generate platform specific distributables (installers, distribution
|
121 | packages, etc.) for you. By default, you can only generate distributables
|
122 | for your current platform. If you want to specify platform / arch, use the
|
123 | `--platform=<platform>` and `--arch=<arch>` arguments, but _please note that
|
124 | some distributables are not available to be built on anything but the platform
|
125 | that is targeted. For example, `appx` (Windows Store) distributables can only
|
126 | be built on Windows._
|
127 |
|
128 | ## Linting your Project
|
129 |
|
130 | ```bash
|
131 | electron-forge lint
|
132 | ```
|
133 |
|
134 | ## Publishing your Project
|
135 |
|
136 | ```bash
|
137 | electron-forge publish
|
138 | ```
|
139 |
|
140 | This will `make` your project and publish any generated artifacts. By default it will publish to
|
141 | GitHub, but you can change the publish target(s) with `--target=YourTarget,YourTarget2`, where the
|
142 | value is a comma-separated list of targets.
|
143 |
|
144 | # Config
|
145 |
|
146 | Once you have generated a project, your `package.json` file will have some
|
147 | default `forge` configuration. Below is the reference structure for this
|
148 | config object:
|
149 |
|
150 | ```javascript
|
151 | {
|
152 | "make_targets": {
|
153 | "win32": ["squirrel"], // An array of win32 make targets
|
154 | "darwin": ["zip", "dmg"], // An array of darwin make targets
|
155 | "linux": ["deb", "rpm", "flatpak"] // An array of linux make targets
|
156 | },
|
157 | "electronPackagerConfig": {},
|
158 | "electronRebuildConfig": {},
|
159 | "electronWinstallerConfig": {},
|
160 | "electronInstallerDMG": {},
|
161 | "electronInstallerFlatpak": {},
|
162 | "electronInstallerDebian": {},
|
163 | "electronInstallerRedhat": {}
|
164 | }
|
165 | ```
|
166 |
|
167 | ## Possible `make` targets
|
168 |
|
169 | | Target Name | Available Platforms | Description | Configurable Options | Default? | Requirements |
|
170 | |-------------|---------------------|-------------|----------------------|----------|--------------|
|
171 | | `zip` | All | Zips your packaged application | None | Yes | `zip` on Darwin/Linux |
|
172 | | `squirrel` | Windows | Generates an installer and `.nupkg` files for Squirrel.Windows | [`electronWinstallerConfig`](https://github.com/electron/windows-installer#usage) | Yes | |
|
173 | | `appx` | Windows | Generates a Windows Store package | [`windowsStoreConfig`](https://github.com/felixrieseberg/electron-windows-store#programmatic-usage) | No | |
|
174 | | `dmg` | Darwin | Generates a DMG file | [`electronInstallerDMG`](https://github.com/mongodb-js/electron-installer-dmg#api) | No | |
|
175 | | `deb` | Linux | Generates a Debian package | [`electronInstallerDebian`](https://github.com/unindented/electron-installer-debian#options) | Yes | [`fakeroot` and `dpkg`](https://github.com/unindented/electron-installer-debian#requirements) |
|
176 | | `rpm` | Linux | Generates an RPM package | [`electronInstallerRedhat`](https://github.com/unindented/electron-installer-redhat#options) | Yes | [`rpm`](https://github.com/unindented/electron-installer-redhatn#requirements) |
|
177 | | `flatpak` | Linux | Generates a [Flatpak](http://flatpak.org/) file | [`electronInstallerFlatpak`](https://github.com/endlessm/electron-installer-flatpak#options) | No | [`flatpak-builder`](https://github.com/endlessm/electron-installer-flatpak#requirements) |
|
178 |
|
179 | ## Configuring `package`
|
180 |
|
181 | You can set `electronPackagerConfig` with any of the options from
|
182 | [Electron Packager](https://github.com/electron-userland/electron-packager/blob/master/docs/api.md), except:
|
183 |
|
184 | * `arch` (use the `--arch` Forge command line argument instead, so it's available to all of Forge)
|
185 | * `asar.unpack` (use `asar.unpackDir` instead)
|
186 | * `dir` (use the `cwd` Forge command line argument instead, so it's available to all of Forge)
|
187 | * `electronVersion` (uses the exact version specified for `electron-prebuilt-compile` in your `devDependencies`)
|
188 | * `out`
|
189 | * `platform` (use the `--platform` Forge command line argument instead, so it's available to all of Forge)
|
190 | * `quiet`
|
191 |
|
192 | You can set `electronRebuildConfig` with any of the options from
|
193 | [Electron Rebuild](https://github.com/electron/electron-rebuild#how-can-i-integrate-this-into-grunt--gulp--whatever), except:
|
194 |
|
195 | * `electronVersion`/`--version` (uses the exact version specified for `electron-prebuilt-compile` in your `devDependencies`)
|
196 | * `arch`/`--arch` (use the `--arch` Forge command line argument instead, so it's available to all of Forge)
|
197 | * `buildPath`/`--module-dir` (uses your project's `node_modules`)
|
198 |
|
199 | **NOTE:** You can also set your `forge` config property of your package.json to point to a JS file that exports the config object:
|
200 |
|
201 | ```js
|
202 | {
|
203 | ...
|
204 | "config": {
|
205 | "forge": "./forge.config.js"
|
206 | }
|
207 | ...
|
208 | }
|
209 | ```
|
210 |
|
211 | **NOTE:** If you use the JSON object then the `afterCopy` and `afterExtract` options are mapped to `require`
|
212 | calls internally, so provide a path to a file that exports your hooks and they will still run. If you use
|
213 | the JS file method mentioned above then you can use functions normally.
|
214 |
|
215 | ## Possible `publish` targets
|
216 |
|
217 | | Target Name | Description | Required Config |
|
218 | |-------------|-------------|-----------------|
|
219 | | 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 <br />`forge.github_repository.owner` - The owner of the GitHub repository<br />`forge.github_repository.name` - The name of the GitHub repository <br />`forge.github_repository.draft` - Create the release as a draft, defaults to `true` <br />`forge.github_repository.prerelease` - Identify the release as a prerelease, defaults to `false` |
|
220 | | 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)_<br />`forge.s3.accessKeyId` - Your access key for your AWS account _(falls back to the standard `AWS_ACCESS_KEY_ID` environment variable)_<br />`forge.s3.bucket` - The name of the S3 bucket to upload to<br />`forge.s3.folder` - The folder path to upload to inside your bucket, defaults to your application version<br />`forge.s3.public` - Whether to make the S3 upload public, defaults to `false` |
|
221 | | [Electron Release Server](https://github.com/ArekSredzki/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<br />`forge.electronReleaseServer.username` - The username for the admin panel on your server<br />`forge.electronReleaseServer.password` - The password for the admin panel on your server |
|
222 |
|
223 | For example:
|
224 |
|
225 | ```javascript
|
226 | // github
|
227 | {
|
228 | // Assume the GitHub repository is at https://github.com/username/repo
|
229 | "github_repository": {
|
230 | "owner": "username",
|
231 | "name": "repo"
|
232 | }
|
233 | }
|
234 |
|
235 | // s3
|
236 | {
|
237 | "s3": {
|
238 | "accessKeyId": "<AWS_ACCESS_KEY>",
|
239 | "bucket": "my_bucket_name",
|
240 | "public": true
|
241 | }
|
242 | }
|
243 |
|
244 | // Electron Release Server
|
245 | {
|
246 | "electronReleaseServer": {
|
247 | "baseUrl": "https://update.mysite.com",
|
248 | "username": "admin",
|
249 | "password": "no_one_will_guess_this"
|
250 | }
|
251 | }
|
252 | ```
|
253 |
|
254 | ## Custom `make` and `publish` targets
|
255 |
|
256 | 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.
|
257 |
|
258 | ### API for `make` targets
|
259 |
|
260 | You must export a Function that returns a Promise. Your function will be called with the following parameters.
|
261 |
|
262 | * `appDir` - The directory containing the packaged application
|
263 | * `appName` - The productName of the application
|
264 | * `targetArch` - The target architecture of the make command
|
265 | * `forgeConfig` - An object representing the users forgeConfig
|
266 | * `packageJSON` - An object representing the users package.json file
|
267 |
|
268 | Your promise must resolve with an array of the artifacts you generated.
|
269 |
|
270 | ### API for `publish` targets
|
271 |
|
272 | You must export a Function that returns a Promise. Your function will be called with the following parameters.
|
273 |
|
274 | * artifactPaths - An array of absolute paths to artifacts to publish
|
275 | * packageJSON - An object representing the users package.json file
|
276 | * forgeConfig - An object representing the users forgeConfig
|
277 | * authToken - The value of `--auth-token`
|
278 | * tag - The value of `--tag`
|
279 | * platform - The platform you are publishing for
|
280 | * arch - The arch you are publishing for
|
281 |
|
282 | You should use `ora` to indicate your publish progress.
|
283 |
|
284 | ## Debugging your application on the command line
|
285 |
|
286 | If you're using Electron 1.7 or later, you can specify the `--inspect-electron` flag, which will
|
287 | set the [Electron `--inspect` flag](http://electronjs.org/docs/tutorial/debugging-main-process#--inspectport)
|
288 | with the default debugger port.
|
289 |
|
290 | For example:
|
291 |
|
292 | ```shell
|
293 | electron-forge start --inspect-electron
|
294 | ```
|
295 |
|
296 | ## Debugging your application through VS Code
|
297 |
|
298 | Debugging your Electron main process through VS Code is ridiculously
|
299 | easy with Forge. Simply add this as a launch config in VSCode and you're
|
300 | good to go.
|
301 |
|
302 | ```js
|
303 | {
|
304 | "type": "node",
|
305 | "request": "launch",
|
306 | "name": "Electron Main",
|
307 | "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-forge-vscode-nix",
|
308 | "windows": {
|
309 | "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-forge-vscode-win.cmd"
|
310 | },
|
311 | // runtimeArgs will be passed directly to your Electron application
|
312 | "runtimeArgs": [
|
313 | "foo",
|
314 | "bar"
|
315 | ],
|
316 | "cwd": "${workspaceRoot}"
|
317 | }
|
318 | ```
|