diff --git a/docs/README.md b/docs/README.md index 3d07efe555..c68013357e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,2 +1 @@ -# Introduction - +# Electron Forge diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index b42fd99e54..b3f384b601 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,6 +1,38 @@ # Summary * [Introduction](README.md) -* [Core Concepts](concepts.md) +* [Configuration](config.md) +* [CLI](cli.md) + * [Import](cli.md#import) + * [Init](cli.md#init) + * [Install](cli.md#install) + * [Lint](cli.md#lint) + * [Make](cli.md#make) + * [Package](cli.md#package) + * [Publish](cli.md#publish) + * [Start](cli.md#start) +* [API Docs](https://docs.electronforge.io) +* Plugins + * [Webpack](plugin/webpack.md) + * [Parcel](plugin/parcel.md) + * [Electron Compile](plugin/compile.md) * Makers - * [AppX](packages/maker/appx/README.md) + * [AppX](maker/appx.md) + * [Deb](maker/dev.md) + * [DMG](maker/dmg.md) + * [Flatpak](maker/flatpak.md) + * [RPM](maker/rpm.md) + * [Snapcraft](maker/snap.md) + * [Squirrel.Windows](maker/squirrel.md) + * [Wix MSI](maker/wix.md) + * [Zip](maker/zip.md) +* Publishers + * [Electron Release Server](publisher/ers.md) + * [GitHub](publisher/github.md) + * [S3](publisher/s3.md) + * [Snapcraft](publisher/snap.md) +* [Extending Electron Forge](extend.md) + * [Writing Plugins](extend.md#writing-plugins) + * [Writing Makers](extend.md#writing-makers) + * [Writing Publishers](extend.md#writing-publishers) + diff --git a/docs/book.json b/docs/book.json index 360ef3a116..12988528c1 100644 --- a/docs/book.json +++ b/docs/book.json @@ -1,5 +1,5 @@ { - "plugins": ["theme-api", "panel"], + "plugins": ["theme-api", "panel", "collapsible-menu", "ace"], "pluginsConfig": { "theme-api": { "theme": "dark" diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000000..0ede5fde03 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,118 @@ +# Electron Forge CLI + +{% method %} +## Installation + +Electron forge's CLI is separate from the core module, to install it you will +have to use the `@electron-forge/cli` module from NPM. + +{% sample lang="sh" %} +```sh +# NPM +npm i -g @electron-forge/cli + +# Yarn +yarn global add @electron-forge/cli +``` + +{% endmethod %} + +## Overview + +At a high level the CLI module is just a proxy to the raw +[API](https://docs.electronforge.io) commands. Almost all the configuation +is still done in your [Forge Config](config), the CLI just provides a handy +way to trigger all the core functionality of Electron Forge (and you should +definitely use it). + +## Commands + +Please note these commands are sorted in alphabetical order, the ones you +probably need to care about are [`start`](#start), [`package`](#package), +[`make`](#make) and [`publish`](#publish). + +### Import + +Maps to `electronForge.import`, will attempt to take an existing Electron app +and make it Forge compatible. Normally this is just created a base forge config +and adding the required dependencies. + +> There are no flags for the Import command + +### Init + +Maps to `electronForge.init`, will initialize a new Forge powered application in +the given directory (defaults to `.`). + +Please note if you want to use a template it must be installed globally before +running the `init` command. + +| Flag | Value | Description | +|------|-------|-------------| +| `--template` | Template Name | Name of the template to use to make this new app| +| `--copy-ci-files` | N/A | Set if you want to copy templated CI files for Travis CI and Appveyor | + +### Install + +Maps to `electronForge.install`, will attempt to install the Electron app +that is published at the given GitHub repository. This command is just a helper +for installing other applications quickly. + +### Lint + +Maps to `electronForge.lint`, will run the `lint` command that your package.json +exposes. If the exit code is 0 no output is shown, otherwise the error output +will be displayed. + +> There are no flags for the Lint command + +### Make + +Maps to `electronForge.make`, will make distributables for your application +based on your forge config and the parameters you pass in. + +| Flag | Value | Description | +|------|-------|-------------| +| `--arch` | Architecture E.g. `x64` | Target architecture to make for | +| `--platform` | Platform E.g. `mas` | Target platform to make for, please note you normally can only target platform X from platform X | +| `--targets` | Comma separated list of maker names | Override your make targets for this run | +| `--skip-package` | N/A | Set if you want to skip the packaging step, useful if you are running sequential makes and want to save time | + +### Package + +Maps to `electronForge.package`, will package your application into a platform +specific format and put the result in a folder. Please note that this does not +make a distributable format, to make proper distributables please use the +[`make`](#make) command. + +| Flag | Value | Description | +|------|-------|-------------| +| `--arch` | Architecture E.g. `x64` | Target architecture to package for | +| `--platform` | Platform E.g. `mas` | Target platform to package for | + +### Publish + +Maps to `electronForge.publish`, will attempt to make the forge application +and then publish it to the publish targets defined in your forge config. + +If you want to publish previously created `make` artifacts you will have to use +the `dry-run` options explained below. + +| Flag | Value | Description | +|------|-------|-------------| +| `--tag` | Version | The version to publish these artifacts as | +| `--target` | Comma separated list of publisher names | Override your publish targets for this run | +| `--dry-run` | N/A | Triggers a publish dry run which saves state and doesn't upload anything | +| `--from-dry-run` | N/A | Attempts to publish artifacts from any dry runs saved on disk | + +### Start + +Maps to `electronForge.start`, will launch the Forge powered application in the +given directory (defaults to `.`). + +| Flag | Value | Description | +|------|-------|-------------| +| `--app-path` | Path to your app from CWD | Override the path to the Electron app to launch (defaults to '.') | +| `--enable-logging` | N/A | Enable advanced logging. This will log internal Electron things | +| `--run-as-node` | N/A | Run the Electron app as a Node.JS script | +| `--inspect-electron` | N/A | Triggers inspect mode on Electron to allow debugging the main process | diff --git a/docs/extend.md b/docs/extend.md new file mode 100644 index 0000000000..3525ad4a96 --- /dev/null +++ b/docs/extend.md @@ -0,0 +1,79 @@ +# Extending Electron Forge + +Electron Forge is designed to be easily extendable by third parties with +whatever build logic you need. The build flow for Electron Forge is split into +two main sections `make` and `publish` and you can define custom targets for +each of those commands. For everything else we have a Plugin API which allows +you to hook into pretty much any part of forge's standard build process and do +whatever you want. + +If there is something you want to be able to do with a plugin/maker/publisher +that isn't currently exposed, please don't hesitate to raise a Feature Request +issue on our [GitHub Repository](https://github.com/electron-userland/electron-forge). + +## Writing Plugins + +An Electron Forge Plugin has to export a single class that extends our base +plugin. The base plugin can be depended on by installing +`@electron-forge/plugin-base`. It can implement two methods, neither are +required: + +{% method %} +### `getHook(hookName: string): Function` + +If implemented this method will be called every time a hook fires inside Forge +and you must look at the `hookName` and either return a function to run for that +hook or return a falsey value to indicate you have no hook to run. + +The possible `hookName` values and the parameters passed to the hook function +you return are documented over in the [Configuration](config) section of the +docs. + +{% sample lang="javascript" %} +{%ace edit=false, lang='javascript', check=false, theme="tomorrow_night" %} +export default class MyPlugin extends PluginBase { + getHook(hookName) { + switch (hookName) { + case 'prePackage': + return this.prePackage; + break; + } + } + + prePackage() { + console.log('running prePackage hook); + } +} +{%endace%} + +{% endmethod %} + +{% method %} +### `startLogic(startOpts: StartOptions): Promise` + +If implemented this method will be called every time the user runs +`electron-forge start`, if you return a `ChildProcess` you can override the +built in start logic and Electron Forge will not spawn it's own process rather +watch the one you returned. If you return `null` forge will spawn Electron +itself but you could still run custom logic such as started compilation for +code or downloading certain binaries before start. + +NOTE: `StartOptions` is documented [on our API site](https://docs.electronforge.io/typedef/index.html#static-typedef-StartOptions) + +{% sample lang="javascript" %} +{%ace edit=false, lang='javascript', check=false, theme="tomorrow_night" %} +export default class MyPlugin extends PluginBase { + async startLogic(opts) { + await this.compileMainProcess(); + return null; + } + + compileMainProcess() { ... } +} +{%endace%} + +{% endmethod %} + +## Writing Makers + +## Writing Publishers \ No newline at end of file diff --git a/docs/styles/website.css b/docs/styles/website.css index 96a934da10..cda1993762 100644 --- a/docs/styles/website.css +++ b/docs/styles/website.css @@ -1,3 +1,11 @@ .gitbook-link { display: none !important; +} + +.ace { + border: none !important; +} + +.api-method-code { + margin-top: 2em; } \ No newline at end of file diff --git a/packages/api/cli/src/electron-forge-publish.js b/packages/api/cli/src/electron-forge-publish.js index 6bc14d07c9..ccd47b67ed 100644 --- a/packages/api/cli/src/electron-forge-publish.js +++ b/packages/api/cli/src/electron-forge-publish.js @@ -12,7 +12,6 @@ import { getMakeOptions } from './electron-forge-make'; program .version(require('../package.json').version) .arguments('[cwd]') - .option('--auth-token', 'Authorization token for your publisher target (if required)') .option('--tag', 'The tag to publish to on GitHub') .option('--target [target[,target...]]', 'The comma-separated deployment targets, defaults to "github"') .option('--dry-run', 'Triggers a publish dry run which saves state and doesn\'t upload anything') diff --git a/packages/api/core/src/api/publish.js b/packages/api/core/src/api/publish.js index 7f02c7fc48..53726e31be 100644 --- a/packages/api/core/src/api/publish.js +++ b/packages/api/core/src/api/publish.js @@ -62,6 +62,7 @@ const publish = async (providedOptions = {}) => { } let packageJSON = await readPackageJSON(dir); + if (tag === null ) tag = packageJSON.version; const forgeConfig = await getForgeConfig(dir); const outDir = providedOptions.outDir || getCurrentOutDir(dir, forgeConfig);