UNPKG

electron-forge/docs/index.html

Version:
1<!DOCTYPE html>
2<html>
3<head>
4  <meta charset="utf-8">
5  <base data-ice="baseUrl">
6  <title data-ice="title">Home | electron-forge</title>
7  <link type="text/css" rel="stylesheet" href="css/style.css">
8  <link type="text/css" rel="stylesheet" href="css/prettify-tomorrow.css">
9  <script src="script/prettify/prettify.js"></script>
10  <script src="script/manual.js"></script>
11<meta name="description" content="A complete tool for building modern Electron applications"><meta property="twitter:card" content="summary"><meta property="twitter:title" content="electron-forge"><meta property="twitter:description" content="A complete tool for building modern Electron applications"></head>
12<body class="layout-container" data-ice="rootContainer">
13
14<header>
15  <a href="./">Home</a>
16  
17  <a href="identifiers.html">Reference</a>
18  <a href="source.html">Source</a>
19  
20  <div class="search-box">
21  <span>
22    <img src="./image/search.png">
23    <span class="search-input-edge"></span><input class="search-input"><span class="search-input-edge"></span>
24  </span>
25    <ul class="search-result"></ul>
26  </div>
27<a style="position:relative; top:3px;" href="https://github.com/electron-userland/electron-forge"><img width="20px" src="./image/github.png"></a></header>
28
29<nav class="navigation" data-ice="nav"><div>
30  <ul>
31    
32  <li data-ice="doc"><span data-ice="kind" class="kind-function">F</span><span data-ice="name"><span><a href="function/index.html#static-function-import">import</a></span></span></li>
33<li data-ice="doc"><span data-ice="kind" class="kind-function">F</span><span data-ice="name"><span><a href="function/index.html#static-function-init">init</a></span></span></li>
34<li data-ice="doc"><span data-ice="kind" class="kind-function">F</span><span data-ice="name"><span><a href="function/index.html#static-function-install">install</a></span></span></li>
35<li data-ice="doc"><span data-ice="kind" class="kind-function">F</span><span data-ice="name"><span><a href="function/index.html#static-function-lint">lint</a></span></span></li>
36<li data-ice="doc"><span data-ice="kind" class="kind-function">F</span><span data-ice="name"><span><a href="function/index.html#static-function-make">make</a></span></span></li>
37<li data-ice="doc"><span data-ice="kind" class="kind-function">F</span><span data-ice="name"><span><a href="function/index.html#static-function-package">package</a></span></span></li>
38<li data-ice="doc"><span data-ice="kind" class="kind-function">F</span><span data-ice="name"><span><a href="function/index.html#static-function-publish">publish</a></span></span></li>
39<li data-ice="doc"><span data-ice="kind" class="kind-function">F</span><span data-ice="name"><span><a href="function/index.html#static-function-start">start</a></span></span></li>
40<li data-ice="doc"><span data-ice="kind" class="kind-typedef">T</span><span data-ice="name"><span><a href="typedef/index.html#static-typedef-ImportOptions">ImportOptions</a></span></span></li>
41<li data-ice="doc"><span data-ice="kind" class="kind-typedef">T</span><span data-ice="name"><span><a href="typedef/index.html#static-typedef-InitOptions">InitOptions</a></span></span></li>
42<li data-ice="doc"><span data-ice="kind" class="kind-typedef">T</span><span data-ice="name"><span><a href="typedef/index.html#static-typedef-InstallOptions">InstallOptions</a></span></span></li>
43<li data-ice="doc"><span data-ice="kind" class="kind-typedef">T</span><span data-ice="name"><span><a href="typedef/index.html#static-typedef-LintOptions">LintOptions</a></span></span></li>
44<li data-ice="doc"><span data-ice="kind" class="kind-typedef">T</span><span data-ice="name"><span><a href="typedef/index.html#static-typedef-MakeOptions">MakeOptions</a></span></span></li>
45<li data-ice="doc"><span data-ice="kind" class="kind-typedef">T</span><span data-ice="name"><span><a href="typedef/index.html#static-typedef-MakeResult">MakeResult</a></span></span></li>
46<li data-ice="doc"><span data-ice="kind" class="kind-typedef">T</span><span data-ice="name"><span><a href="typedef/index.html#static-typedef-PackageOptions">PackageOptions</a></span></span></li>
47<li data-ice="doc"><span data-ice="kind" class="kind-typedef">T</span><span data-ice="name"><span><a href="typedef/index.html#static-typedef-PublishOptions">PublishOptions</a></span></span></li>
48<li data-ice="doc"><span data-ice="kind" class="kind-typedef">T</span><span data-ice="name"><span><a href="typedef/index.html#static-typedef-StartOptions">StartOptions</a></span></span></li>
49</ul>
50</div>
51</nav>
52
53<div class="content" data-ice="content"><div data-ice="index" class="github-markdown"><h2 id="electron-forge">Electron Forge</h2><p><a href="https://travis-ci.org/electron-userland/electron-forge"><img src="https://travis-ci.org/electron-userland/electron-forge.svg?branch=master" alt="Linux/macOS Build Status"></a>
54<a href="https://ci.appveyor.com/project/electron-userland/electron-forge"><img src="https://ci.appveyor.com/api/projects/status/79ae80nek1eucyy3?svg=true" alt="Windows Build status"></a>
55<a href="http://commitizen.github.io/cz-cli/"><img src="https://img.shields.io/badge/commitizen-friendly-brightgreen.svg" alt="Commitizen friendly"></a>
56<a href="https://www.npmjs.com/package/electron-forge"><img src="https://badge.fury.io/js/electron-forge.svg" alt="npm version"></a>
57<a href="https://www.npmjs.com/package/electron-forge"><img src="https://img.shields.io/npm/dt/electron-forge.svg?maxAge=2592000" alt="npm"></a>
58<a href="https://github.com/electron-userland/electron-forge/blob/master/LICENSE"><img src="https://img.shields.io/github/license/electron-userland/electron-forge.svg" alt="license"></a>
59<img src="https://img.shields.io/badge/Status-%20Ready%20for%20Awesome-red.svg" alt="status"></p>
60<p>A complete tool for building modern Electron applications.</p>
61<p>Electron Forge unifies the existing (and well maintained) build tools for
62Electron development into a simple, easy to use package so that anyone can
63jump right in to Electron development.</p>
64<h1 id="getting-started">Getting Started</h1><p><strong>Note</strong>: Electron Forge requires Node 6 or above, plus git installed.</p>
65<pre><code class="lang-bash"><code class="source-code prettyprint">npm install -g electron-forge
66electron-forge init my-new-app
67cd my-new-app
68npm start</code>
69</code></pre>
70<p>Alternatively, if you have a more recent version of <code>npm</code> or <code>yarn</code>, you can use
71<a href="https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b"><code>npx</code></a>,
72or
73<a href="https://yarnpkg.com/blog/2017/05/12/introducing-yarn/"><code>yarn create</code></a>.</p>
74<pre><code class="lang-bash"><code class="source-code prettyprint">npx electron-forge init my-new-app
75# or
76yarn create electron-app my-new-app
77
78# then
79cd my-new-app
80npm start</code>
81</code></pre>
82<h1 id="project-goals">Project Goals</h1><ol>
83<li>Starting with Electron should be as simple as a single command.</li>
84<li>Developers shouldn&apos;t have to worry about <code>babel</code>, <code>browserify</code>, <code>webpack</code>,
85native module rebuilding, etc.  Everything should &quot;just work&quot; for them out
86of the box.</li>
87<li>Everything from creating the project to packaging the project for release
88should be handled by one dependency in a standard way while still offering
89users maximum choice and freedom.</li>
90</ol>
91<p>With these goals in mind, under the hood this project uses, among others:</p>
92<ul>
93<li><a href="https://github.com/electron/electron-compile"><code>electron-compile</code></a>: a tool
94that lets you use modern and futuristic languages inside Electron without
95worrying about transpiling or build tooling.</li>
96<li><a href="https://github.com/electron/electron-rebuild"><code>electron-rebuild</code></a>:
97Automatically recompiles native Node.js modules against the correct
98Electron version.</li>
99<li><a href="https://github.com/electron-userland/electron-packager">Electron Packager</a>:
100Customizes and bundles your Electron app to get it ready for distribution.</li>
101</ul>
102<h1 id="usage">Usage</h1><h2 id="starting-a-new-project">Starting a new Project</h2><pre><code class="lang-bash"><code class="source-code prettyprint">npm install -g electron-forge
103electron-forge init my-new-project</code>
104</code></pre>
105<p>This command will generate a brand new project folder and install all your Node
106module dependencies, so you will be all set to go.  By default we will also
107install the <code>airbnb</code> linting modules.  If you want to follow the <code>standard</code>
108linting rules instead, use the <code>--lintstyle=standard</code> argument.</p>
109<p>You can also start a project with your
110<a href="https://electronforge.io/templates">favorite framework</a> with the <code>--template</code>
111argument.  E.g. <code>--template=react</code>.</p>
112<h2 id="importing-an-existing-project">Importing an existing Project</h2><pre><code class="lang-bash"><code class="source-code prettyprint">electron-forge import existing-project-directory</code>
113</code></pre>
114<p>Given an existing Electron project, this command will attempt to interactively
115navigate through the process of importing it to the Electron Forge format, so
116the commands listed below can be used. This includes being prompted to remove
117existing Electron build tools in favor of Electron Forge equivalents.</p>
118<h2 id="launching-your-project">Launching your Project</h2><pre><code class="lang-bash"><code class="source-code prettyprint">electron-forge start</code>
119</code></pre>
120<p>Any arguments after &quot;start&quot; will be passed through to your application when
121it&apos;s launched.</p>
122<h2 id="packaging-your-project">Packaging your Project</h2><pre><code class="lang-bash"><code class="source-code prettyprint">electron-forge package</code>
123</code></pre>
124<p>Yes, it really is that simple.  If you want to specify platform / arch, use the
125<code>--platform=&lt;platform&gt;</code> and <code>--arch=&lt;arch&gt;</code> arguments.</p>
126<h2 id="generating-a-distributable-for-your-project">Generating a distributable for your Project</h2><pre><code class="lang-bash"><code class="source-code prettyprint">electron-forge make</code>
127</code></pre>
128<p>This will generate platform specific distributables (installers, distribution
129packages, etc.) for you. Note that you can only generate distributables for your
130current platform.</p>
131<h2 id="linting-your-project">Linting your Project</h2><pre><code class="lang-bash"><code class="source-code prettyprint">electron-forge lint</code>
132</code></pre>
133<h2 id="publishing-your-project">Publishing your Project</h2><pre><code class="lang-bash"><code class="source-code prettyprint">electron-forge publish</code>
134</code></pre>
135<p>This will <code>make</code> your project and publish any generated artifacts.  By default it will publish to GitHub but you can change the publish target with <code>--target=YourTarget</code>.</p>
136<h1 id="config">Config</h1><p>Once you have generated a project, your <code>package.json</code> file will have some
137default <code>forge</code> configuration.  Below is the reference structure for this
138config object:</p>
139<pre><code class="lang-javascript"><code class="source-code prettyprint">{
140  &quot;make_targets&quot;: {
141    &quot;win32&quot;: [&quot;squirrel&quot;], // An array of win32 make targets
142    &quot;darwin&quot;: [&quot;zip&quot;, &quot;dmg&quot;], // An array of darwin make targets
143    &quot;linux&quot;: [&quot;deb&quot;, &quot;rpm&quot;, &quot;flatpak&quot;] // An array of linux make targets
144  },
145  &quot;electronPackagerConfig&quot;: {},
146  &quot;electronWinstallerConfig&quot;: {},
147  &quot;electronInstallerDMG&quot;: {},
148  &quot;electronInstallerFlatpak&quot;: {},
149  &quot;electronInstallerDebian&quot;: {},
150  &quot;electronInstallerRedhat&quot;: {}
151}</code>
152</code></pre>
153<h2 id="possible--code-make--code--targets">Possible <code>make</code> targets</h2><table>
154<thead>
155<tr>
156<th>Target Name</th>
157<th>Available Platforms</th>
158<th>Description</th>
159<th>Configurable Options</th>
160<th>Default?</th>
161<th>Requirements</th>
162</tr>
163</thead>
164<tbody>
165<tr>
166<td><code>zip</code></td>
167<td>All</td>
168<td>Zips your packaged application</td>
169<td>None</td>
170<td>Yes</td>
171<td><code>zip</code> on Darwin/Linux</td>
172</tr>
173<tr>
174<td><code>squirrel</code></td>
175<td>Windows</td>
176<td>Generates an installer and <code>.nupkg</code> files for Squirrel.Windows</td>
177<td><a href="https://github.com/electron/windows-installer#usage"><code>electronWinstallerConfig</code></a></td>
178<td>Yes</td>
179<td></td>
180</tr>
181<tr>
182<td><code>appx</code></td>
183<td>Windows</td>
184<td>Generates a Windows Store package</td>
185<td><a href="https://github.com/felixrieseberg/electron-windows-store#programmatic-usage"><code>windowsStoreConfig</code></a></td>
186<td>No</td>
187<td></td>
188</tr>
189<tr>
190<td><code>dmg</code></td>
191<td>Darwin</td>
192<td>Generates a DMG file</td>
193<td><a href="https://github.com/mongodb-js/electron-installer-dmg#api"><code>electronInstallerDMG</code></a></td>
194<td>No</td>
195<td></td>
196</tr>
197<tr>
198<td><code>deb</code></td>
199<td>Linux</td>
200<td>Generates a Debian package</td>
201<td><a href="https://github.com/unindented/electron-installer-debian#options"><code>electronInstallerDebian</code></a></td>
202<td>Yes</td>
203<td><a href="https://github.com/unindented/electron-installer-debian#requirements"><code>fakeroot</code> and <code>dpkg</code></a></td>
204</tr>
205<tr>
206<td><code>rpm</code></td>
207<td>Linux</td>
208<td>Generates an RPM package</td>
209<td><a href="https://github.com/unindented/electron-installer-redhat#options"><code>electronInstallerRedhat</code></a></td>
210<td>Yes</td>
211<td><a href="https://github.com/unindented/electron-installer-redhatn#requirements"><code>rpm</code></a></td>
212</tr>
213<tr>
214<td><code>flatpak</code></td>
215<td>Linux</td>
216<td>Generates a <a href="http://flatpak.org/">Flatpak</a> file</td>
217<td><a href="https://github.com/endlessm/electron-installer-flatpak#options"><code>electronInstallerFlatpak</code></a></td>
218<td>No</td>
219<td><a href="https://github.com/endlessm/electron-installer-flatpak#requirements"><code>flatpak-builder</code></a></td>
220</tr>
221</tbody>
222</table>
223<h2 id="configuring--code-package--code-">Configuring <code>package</code></h2><p>You can set <code>electronPackagerConfig</code> with any of the options from
224<a href="https://github.com/electron-userland/electron-packager/blob/master/docs/api.md">Electron Packager</a>, except:</p>
225<ul>
226<li><code>arch</code></li>
227<li><code>asar.unpack</code> (use <code>asar.unpackDir</code> instead)</li>
228<li><code>dir</code></li>
229<li><code>electronVersion</code> (uses the exact version specified for <code>electron-prebuilt-compile</code> in your <code>devDependencies</code>)</li>
230<li><code>out</code></li>
231<li><code>platform</code></li>
232<li><code>quiet</code></li>
233</ul>
234<p><strong>NOTE:</strong> You can also set your <code>forge</code> config property of your package.json to point to a JS file that exports the config object:</p>
235<pre><code class="lang-js"><code class="source-code prettyprint">{
236  ...
237  &quot;config&quot;: {
238    &quot;forge&quot;: &quot;./forge.config.js&quot;
239  }
240  ...
241}</code>
242</code></pre>
243<p><strong>NOTE:</strong> If you use the JSON object then the <code>afterCopy</code> and <code>afterExtract</code> options are mapped to <code>require</code>
244calls internally, so provide a path to a file that exports your hooks and they will still run.  If you use
245the JS file method mentioned above then you can use functions normally.</p>
246<h2 id="possible--code-publish--code--targets">Possible <code>publish</code> targets</h2><table>
247<thead>
248<tr>
249<th>Target Name</th>
250<th>Description</th>
251<th>Required Config</th>
252</tr>
253</thead>
254<tbody>
255<tr>
256<td>GitHub Releases - <code>github</code></td>
257<td>Makes a new release for the current version (if required) and uploads the make artifacts as release assets</td>
258<td><code>process.env.GITHUB_TOKEN</code> - A personal access token with access to your releases <br><code>forge.github_repository.owner</code> - The owner of the GitHub repository<br><code>forge.github_repository.name</code> - The name of the GitHub repository <br><code>forge.github_repository.draft</code> - Create the release as a draft, defaults to <code>true</code> <br><code>forge.github_repository.prerelease</code> - Identify the release as a prerelease, defaults to <code>false</code></td>
259</tr>
260<tr>
261<td>Amazon S3 - <code>s3</code></td>
262<td>Uploads your artifacts to the given S3 bucket</td>
263<td><code>process.env.ELECTRON_FORGE_S3_SECRET_ACCESS_KEY</code> - Your secret access token for your AWS account _(falls back to the standard <code>AWS_SECRET_ACCESS_KEY</code> environment variable)<em><br><code>forge.s3.accessKeyId</code> - Your access key for your AWS account </em>(falls back to the standard <code>AWS_ACCESS_KEY_ID</code> environment variable)_<br><code>forge.s3.bucket</code> - The name of the S3 bucket to upload to<br><code>forge.s3.folder</code> - The folder path to upload to inside your bucket, defaults to your application version<br><code>forge.s3.public</code> - Whether to make the S3 upload public, defaults to <code>false</code></td>
264</tr>
265<tr>
266<td><a href="https://github.com/ArekSredzki/electron-release-server">Electron Release Server</a> - <code>electron-release-server</code></td>
267<td>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.</td>
268<td><code>forge.electronReleaseServer.baseUrl</code> - The base URL of your release server, no trailing slash<br><code>forge.electronReleaseServer.username</code> - The username for the admin panel on your server<br><code>forge.electronReleaseServer.password</code> - The password for the admin panel on your server</td>
269</tr>
270</tbody>
271</table>
272<p>For example:</p>
273<pre><code class="lang-javascript"><code class="source-code prettyprint">// github
274{
275  // Assume the GitHub repository is at https://github.com/username/repo
276  &quot;github_repository&quot;: {
277    &quot;owner&quot;: &quot;username&quot;,
278    &quot;name&quot;: &quot;repo&quot;
279  }
280}
281
282// s3
283{
284  &quot;s3&quot;: {
285    &quot;accessKeyId&quot;: &quot;&lt;AWS_ACCESS_KEY&gt;&quot;,
286    &quot;bucket&quot;: &quot;my_bucket_name&quot;,
287    &quot;public&quot;: true
288  }
289}
290
291// Electron Release Server
292{
293  &quot;electronReleaseServer&quot;: {
294    &quot;baseUrl&quot;: &quot;https://update.mysite.com&quot;,
295    &quot;username&quot;: &quot;admin&quot;,
296    &quot;password&quot;: &quot;no_one_will_guess_this&quot;
297  }
298}</code>
299</code></pre>
300<h2 id="custom--code-make--code--and--code-publish--code--targets">Custom <code>make</code> and <code>publish</code> targets</h2><p>You can make your own custom targets for the <code>make</code> and <code>publish</code> targets.  If you publish them as <code>electron-forge-publisher-{name}</code> or <code>electron-forge-maker-{name}</code> you can then just specify <code>{name}</code> as your make / publish target.  The API for each is documented below.</p>
301<h3 id="api-for--code-make--code--targets">API for <code>make</code> targets</h3><p>You must export a Function that returns a Promise.  Your function will be called with the following parameters.</p>
302<ul>
303<li><code>appDir</code> - The directory containing the packaged application</li>
304<li><code>appName</code> - The productName of the application</li>
305<li><code>targetArch</code> - The target architecture of the make command</li>
306<li><code>forgeConfig</code> - An object representing the users forgeConfig</li>
307<li><code>packageJSON</code> - An object representing the users package.json file</li>
308</ul>
309<p>Your promise must resolve with an array of the artifacts you generated.</p>
310<h3 id="api-for--code-publish--code--targets">API for <code>publish</code> targets</h3><p>You must export a Function that returns a Promise.  Your function will be called with the following parameters.</p>
311<ul>
312<li>artifactPaths - An array of absolute paths to artifacts to publish</li>
313<li>packageJSON - An object representing the users package.json file</li>
314<li>forgeConfig - An object representing the users forgeConfig</li>
315<li>authToken - The value of <code>--auth-token</code></li>
316<li>tag - The value of <code>--tag</code></li>
317<li>platform - The platform you are publishing for</li>
318<li>arch - The arch you are publishing for</li>
319</ul>
320<p>You should use <code>ora</code> to indicate your publish progress.</p>
321<h2 id="debugging-your-application-through-vs-code">Debugging your application through VS Code</h2><p>Debugging your Electron main process through VS Code is ridiculously
322easy with Forge.  Simply add this as a launch config in VSCode and you&apos;re
323good to go.</p>
324<pre><code class="lang-js"><code class="source-code prettyprint">{
325  &quot;type&quot;: &quot;node&quot;,
326  &quot;request&quot;: &quot;launch&quot;,
327  &quot;name&quot;: &quot;Electron Main&quot;,
328  &quot;runtimeExecutable&quot;: &quot;${workspaceRoot}/node_modules/.bin/electron-forge-vscode-nix&quot;,
329  &quot;windows&quot;: {
330    &quot;runtimeExecutable&quot;: &quot;${workspaceRoot}/node_modules/.bin/electron-forge-vscode-win.cmd&quot;
331  },
332  // runtimeArgs will be passed directly to your Electron application
333  &quot;runtimeArgs&quot;: [
334    &quot;foo&quot;,
335    &quot;bar&quot;
336  ],
337  &quot;cwd&quot;: &quot;${workspaceRoot}&quot;
338}</code>
339</code></pre>
340</div>
341</div>
342
343<footer class="footer">
344  Generated by <a href="https://esdoc.org">ESDoc<span data-ice="esdocVersion">(1.0.1)</span><img src="./image/esdoc-logo-mini-black.png"></a>
345</footer>
346
347<script src="script/search_index.js"></script>
348<script src="script/search.js"></script>
349<script src="script/pretty-print.js"></script>
350<script src="script/inherited-summary.js"></script>
351<script src="script/test-summary.js"></script>
352<script src="script/inner-link.js"></script>
353<script src="script/patch-for-local.js"></script>
354</body>
355</html>