electron-forge

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <base data-ice="baseUrl"> <title data-ice="title">API Document</title> <link type="text/css" rel="stylesheet" href="css/style.css"> <link type="text/css" rel="stylesheet" href="css/prettify-tomorrow.css"> <script src="script/prettify/prettify.js"></script> <script src="script/manual.js"></script> </head> <body class="layout-container" data-ice="rootContainer"> <header> <a href="./">Home</a> <a href="identifiers.html">Reference</a> <a href="source.html">Source</a> <a data-ice="repoURL" href="https://github.com/electron-userland/electron-forge" class="repo-url-github">Repository</a> <div class="search-box"> <span> <img src="./image/search.png"> <span class="search-input-edge"></span><input class="search-input"><span class="search-input-edge"></span> </span> <ul class="search-result"></ul> </div> </header> <nav class="navigation" data-ice="nav"><div> <ul> <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> <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> <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> <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> <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> <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> <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> <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> <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> <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> <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> <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> <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> <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> <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> <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> </ul> </div> </nav> <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> <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> <a href="http://commitizen.github.io/cz-cli/"><img src="https://img.shields.io/badge/commitizen-friendly-brightgreen.svg" alt="Commitizen friendly"></a> <a href="https://www.npmjs.com/package/electron-forge"><img src="https://badge.fury.io/js/electron-forge.svg" alt="npm version"></a> <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> <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> <img src="https://img.shields.io/badge/Status-%20Ready%20for%20Awesome-red.svg" alt="status"></p> <p>A complete tool for building modern Electron applications.</p> <p>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.</p> <h1 id="getting-started">Getting Started</h1> <p><strong>Note</strong>: Electron Forge requires Node 6 or above, plus git installed.</p> <pre><code class="lang-bash"><code class="source-code prettyprint">npm install -g electron-forge electron-forge init my-new-app cd my-new-app electron-forge start</code> </code></pre> <h1 id="project-goals">Project Goals</h1> <ol> <li>Starting with Electron should be as simple as a single command.</li> <li>Developers shouldn't have to worry about <code>babel</code>, <code>browserify</code>, <code>webpack</code>, etc. Everything should "just work" for them out of the box.</li> <li>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.</li> </ol> <p>With these goals in mind, under the hood this project uses <a href="https://github.com/electron/electron-compile"><code>electron-compile</code></a>: a tool that lets you use modern and futuristic languages inside Electron without worrying about transpiling or build tooling.</p> <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 electron-forge init my-new-project</code> </code></pre> <p>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 <code>airbnb</code> linting modules. If you want to follow the <code>standard</code> linting rules instead, use the <code>--lintstyle=standard</code> argument.</p> <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> </code></pre> <p>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.</p> <h2 id="launching-your-project">Launching your Project</h2> <pre><code class="lang-bash"><code class="source-code prettyprint">electron-forge start</code> </code></pre> <p>Any arguments after "start" will be passed through to your application when it's launched.</p> <h2 id="packaging-your-project">Packaging your Project</h2> <pre><code class="lang-bash"><code class="source-code prettyprint">electron-forge package</code> </code></pre> <p>Yes, it really is that simple. If you want to specify platform / arch, use the <code>--platform=<platform></code> and <code>--arch=<arch></code> arguments.</p> <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> </code></pre> <p>This will generate platform specific distributables (installers, distribution packages, etc.) for you. Note that you can only generate distributables for your current platform.</p> <h2 id="linting-your-project">Linting your Project</h2> <pre><code class="lang-bash"><code class="source-code prettyprint">electron-forge lint</code> </code></pre> <h2 id="publishing-your-project">Publishing your Project</h2> <pre><code class="lang-bash"><code class="source-code prettyprint">electron-forge publish</code> </code></pre> <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> <h1 id="config">Config</h1> <p>Once you have generated a project, your <code>package.json</code> file will have some default <code>forge</code> configuration. Below is the reference structure for this config object:</p> <pre><code class="lang-javascript"><code class="source-code prettyprint">{ "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": {} }</code> </code></pre> <h2 id="possible-make-targets">Possible <code>make</code> targets</h2> <table> <thead> <tr> <th>Target Name</th> <th>Available Platforms</th> <th>Description</th> <th>Configurable Options</th> <th>Default?</th> <th>Requirements</th> </tr> </thead> <tbody> <tr> <td><code>zip</code></td> <td>All</td> <td>Zips your packaged application</td> <td>None</td> <td>Yes</td> <td><code>zip</code> on Darwin/Linux</td> </tr> <tr> <td><code>squirrel</code></td> <td>Windows</td> <td>Generates an installer and <code>.nupkg</code> files for Squirrel.Windows</td> <td><a href="https://github.com/electron/windows-installer#usage"><code>electronWinstallerConfig</code></a></td> <td>Yes</td> <td></td> </tr> <tr> <td><code>appx</code></td> <td>Windows</td> <td>Generates a Windows Store package</td> <td><a href="https://github.com/felixrieseberg/electron-windows-store#programmatic-usage"><code>windowsStoreConfig</code></a></td> <td>No</td> <td></td> </tr> <tr> <td><code>dmg</code></td> <td>Darwin</td> <td>Generates a DMG file</td> <td><a href="https://github.com/mongodb-js/electron-installer-dmg#api"><code>electronInstallerDMG</code></a></td> <td>No</td> <td></td> </tr> <tr> <td><code>deb</code></td> <td>Linux</td> <td>Generates a Debian package</td> <td><a href="https://github.com/unindented/electron-installer-debian#options"><code>electronInstallerDebian</code></a></td> <td>Yes</td> <td><a href="https://github.com/unindented/electron-installer-debian#requirements"><code>fakeroot</code> and <code>dpkg</code></a></td> </tr> <tr> <td><code>rpm</code></td> <td>Linux</td> <td>Generates an RPM package</td> <td><a href="https://github.com/unindented/electron-installer-redhat#options"><code>electronInstallerRedhat</code></a></td> <td>Yes</td> <td><a href="https://github.com/unindented/electron-installer-redhatn#requirements"><code>rpm</code></a></td> </tr> <tr> <td><code>flatpak</code></td> <td>Linux</td> <td>Generates a <a href="http://flatpak.org/">Flatpak</a> file</td> <td><a href="https://github.com/endlessm/electron-installer-flatpak#options"><code>electronInstallerFlatpak</code></a></td> <td>No</td> <td><a href="https://github.com/endlessm/electron-installer-flatpak#requirements"><code>flatpak-builder</code></a></td> </tr> </tbody> </table> <h2 id="configuring-package-">Configuring <code>package</code></h2> <p>You can set <code>electronPackagerConfig</code> with <strong>any</strong> of the options from <a href="https://github.com/electron-userland/electron-packager/blob/master/docs/api.md">Electron Packager</a>.</p> <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> <pre><code class="lang-js"><code class="source-code prettyprint">{ ... "config": { "forge": "./forge.config.js" } ... }</code> </code></pre> <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> 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.</p> <h2 id="possible-publish-targets">Possible <code>publish</code> targets</h2> <table> <thead> <tr> <th>Target Name</th> <th>Description</th> <th>Required Config</th> </tr> </thead> <tbody> <tr> <td>github</td> <td>Makes a new release for the current version (if required) and uploads the make artifacts as release assets</td> <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</td> </tr> </tbody> </table> <h2 id="custom-make-and-publish-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> <h3 id="api-for-make-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> <ul> <li><code>appDir</code> - The directory containing the packaged application</li> <li><code>appName</code> - The productName of the application</li> <li><code>targetArch</code> - The target architecture of the make command</li> <li><code>forgeConfig</code> - An object representing the users forgeConfig</li> <li><code>packageJSON</code> - An object representing the users package.json file</li> </ul> <p>Your promise must resolve with an array of the artifacts you generated.</p> <h3 id="api-for-publish-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> <ul> <li>artifactPaths - An array of absolute paths to artifacts to publish</li> <li>packageJSON - An object representing the users package.json file</li> <li>forgeConfig - An object representing the users forgeConfig</li> <li>authToken - The value of <code>--auth-token</code></li> <li>tag - The value of <code>--tag</code></li> </ul> <p>You should use <code>ora</code> to indicate your publish progress.</p> </div> </div> <footer class="footer"> Generated by <a href="https://esdoc.org">ESDoc<span data-ice="esdocVersion">(0.5.2)</span><img src="./image/esdoc-logo-mini-black.png"></a> </footer> <script src="script/search_index.js"></script> <script src="script/search.js"></script> <script src="script/pretty-print.js"></script> <script src="script/inherited-summary.js"></script> <script src="script/test-summary.js"></script> <script src="script/inner-link.js"></script> <script src="script/patch-for-local.js"></script> </body> </html>