diff --git a/README.md b/README.md index ac0f5ef91e..c29ad314aa 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,352 @@ -# Initial page - -{% api-method method="get" host="https://api.cakes.com" path="/v1/cakes/:id" %} -{% api-method-summary %} -Get Cakes -{% endapi-method-summary %} - -{% api-method-description %} -This endpoint allows you to get free cakes. -{% endapi-method-description %} - -{% api-method-spec %} -{% api-method-request %} -{% api-method-path-parameters %} -{% api-method-parameter name="id" type="string" %} -ID of the cake to get, for free of course. -{% endapi-method-parameter %} -{% endapi-method-path-parameters %} - -{% api-method-headers %} -{% api-method-parameter name="Authentication" type="string" required=true %} -Authentication token to track down who is emptying our stocks. -{% endapi-method-parameter %} -{% endapi-method-headers %} - -{% api-method-query-parameters %} -{% api-method-parameter name="recipe" type="string" %} -The API will do its best to find a cake matching the provided recipe. -{% endapi-method-parameter %} - -{% api-method-parameter name="gluten" type="boolean" %} -Whether the cake should be gluten-free or not. -{% endapi-method-parameter %} -{% endapi-method-query-parameters %} -{% endapi-method-request %} - -{% api-method-response %} -{% api-method-response-example httpCode=200 %} -{% api-method-response-example-description %} -Cake successfully retrieved. -{% endapi-method-response-example-description %} +Electron Forge +-------------- +[![Linux/macOS Build Status](https://travis-ci.org/electron-userland/electron-forge.svg?branch=master)](https://travis-ci.org/electron-userland/electron-forge) +[![Windows Build status](https://ci.appveyor.com/api/projects/status/79ae80nek1eucyy3?svg=true)](https://ci.appveyor.com/project/electron-userland/electron-forge) +[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) +[![npm version](https://badge.fury.io/js/electron-forge.svg)](https://www.npmjs.com/package/electron-forge) +[![npm](https://img.shields.io/npm/dt/electron-forge.svg?maxAge=2592000)](https://www.npmjs.com/package/electron-forge) +[![license](https://img.shields.io/github/license/electron-userland/electron-forge.svg)](https://github.com/electron-userland/electron-forge/blob/master/LICENSE) +![status](https://img.shields.io/badge/Status-%20Ready%20for%20Awesome-red.svg) + +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. + +---- + +## :rotating_light: :construction: **WARNING** :construction: :rotating_light: + +:building_construction: + +The `master` branch is a rewrite of Electron Forge that will eventually be the 6.x series. If you +are looking for the 5.x series (the version currently published to NPM), please view the [5.x branch](https://github.com/electron-userland/electron-forge/tree/5.x). + +---- + +[Website](https://electronforge.io) | +[Goals](#project-goals) | +[Usage](#usage) | +[Configuration](#config) | +[Support](https://github.com/electron-userland/electron-forge/blob/master/SUPPORT.md) | +[Contributing](https://github.com/electron-userland/electron-forge/blob/master/CONTRIBUTING.md) | +[Changelog](https://github.com/electron-userland/electron-forge/blob/master/CHANGELOG.md) + +# Getting Started + +**Note**: Electron Forge requires Node 6 or above, plus git installed. + +```bash +npm install -g electron-forge +electron-forge init my-new-app +cd my-new-app +npm start +``` + +Alternatively, if you have a more recent version of `npm` or `yarn`, you can use +[`npx`](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), +or +[`yarn create`](https://yarnpkg.com/blog/2017/05/12/introducing-yarn/). + +```bash +npx electron-forge init my-new-app +# or +yarn create electron-app my-new-app + +# then +cd my-new-app +npm 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`, + native module rebuilding, 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, among others: + +* [`electron-rebuild`](https://github.com/electron/electron-rebuild): + Automatically recompiles native Node.js modules against the correct + Electron version. +* [Electron Packager](https://github.com/electron-userland/electron-packager): + Customizes and bundles your Electron app to get it ready for distribution. + +# Usage + +## Starting a new Project + +```bash +npm install -g electron-forge +electron-forge init my-new-project +``` + +This command will generate a brand new project folder and install all your Node +module 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. + +You can also start a project with your +[favorite framework](https://electronforge.io/templates) with the `--template` +argument. E.g. `--template=react`. + +If you'd like to have pre-made configuration files for Travis CI and AppVeyor CI to automatically +build and deploy distributables to GitHub, use the `--copy-ci-files` argument. + +## Importing an existing Project + +```bash +electron-forge import existing-project-directory +``` + +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. + +## Launching your Project + +```bash +electron-forge start +``` + +Any arguments after "start" will be passed through to your application when +it's launched. + +## Packaging your Project + +```bash +electron-forge package +``` + +Yes, it really is that simple. If you want to specify platform / arch, use the +`--platform=` and `--arch=` arguments. + +## Generating a distributable for your Project + +```bash +electron-forge make +``` + +This will generate platform specific distributables (installers, distribution +packages, etc.) for you. By default, you can only generate distributables +for your current platform. If you want to specify platform / arch, use the +`--platform=` and `--arch=` arguments, but _please note that +some distributables are not available to be built on anything but the platform +that is targeted. For example, `appx` (Windows Store) distributables can only +be built on Windows._ + +## Linting your Project + +```bash +electron-forge lint +``` + +## Publishing your Project + +```bash +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(s) with `--target=YourTarget,YourTarget2`, where the +value is a comma-separated list of targets. + +# 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: ```javascript { - "name": "Cake's name", - "recipe": "Cake's recipe name", - "cake": "Binary cake" + "make_targets": { + "win32": ["squirrel"], // An array of win32 make targets + "darwin": ["zip", "dmg"], // An array of darwin make targets + "linux": ["deb", "rpm", "flatpak", "snap"] // An array of linux make targets + }, + "electronPackagerConfig": {}, + "electronRebuildConfig": {}, + "electronWinstallerConfig": {}, + "electronInstallerDMG": {}, + "electronInstallerFlatpak": {}, + "electronInstallerDebian": {}, + "electronInstallerRedhat": {}, + "electronInstallerSnap": {} +} +``` + +## 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`](https://github.com/electron/windows-installer#usage) | Yes | | +| `appx` | Windows | Generates a Windows Store package | [`windowsStoreConfig`](https://github.com/felixrieseberg/electron-windows-store#programmatic-usage) | No | | +| `wix` | Windows | Generates a traditional MSI file | [`electronWixMSIConfig`](https://github.com/felixrieseberg/electron-wix-msi#configuration) | No | [Wix Toolit](https://github.com/felixrieseberg/electron-wix-msi#prerequisites) | +| `dmg` | Darwin | Generates a DMG file | [`electronInstallerDMG`](https://github.com/mongodb-js/electron-installer-dmg#api) | No | | +| `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) | +| `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) | +| `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) | +| `snap` | Linux | Generates a [Snap](https://snapcraft.io/) file | [`electronInstallerSnap`](https://github.com/electron-userland/electron-installer-snap/blob/master/docs/api.md#options) | No | [`snapcraft`](https://snapcraft.io/docs/build-snaps/#install-snapcraft) | + +## Configuring `package` + +You can set `electronPackagerConfig` with any of the options from +[Electron Packager](https://github.com/electron-userland/electron-packager/blob/master/docs/api.md), except: + +* `arch` (use the `--arch` Forge command line argument instead, so it's available to all of Forge) +* `asar.unpack` (use `asar.unpackDir` instead) +* `dir` (use the `cwd` Forge command line argument instead, so it's available to all of Forge) +* `electronVersion` (uses the exact version specified for `electron` in your `devDependencies`) +* `out` +* `platform` (use the `--platform` Forge command line argument instead, so it's available to all of Forge) +* `quiet` + +You can set `electronRebuildConfig` with any of the options from +[Electron Rebuild](https://github.com/electron/electron-rebuild#how-can-i-integrate-this-into-grunt--gulp--whatever), except: + +* `electronVersion`/`--version` (uses the exact version specified for `electron` in your `devDependencies`) +* `arch`/`--arch` (use the `--arch` Forge command line argument instead, so it's available to all of Forge) +* `buildPath`/`--module-dir` (uses your project's `node_modules`) + +**NOTE:** You can also set your `forge` config property of your package.json to point to a JS file that exports the config object: + +```js +{ + ... + "config": { + "forge": "./forge.config.js" + } + ... } ``` -{% endapi-method-response-example %} -{% api-method-response-example httpCode=404 %} -{% api-method-response-example-description %} -Could not find a cake matching this query. -{% endapi-method-response-example-description %} +**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 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
`forge.github_repository.owner` - The owner of the GitHub repository
`forge.github_repository.name` - The name of the GitHub repository
`forge.github_repository.draft` - Create the release as a draft, defaults to `true`
`forge.github_repository.prerelease` - Identify the release as a prerelease, defaults to `false`
`forge.github_repository.options` - An `Object` of [connection options](https://github.com/octokit/rest.js#usage), e.g., GitHub Enterprise settings or HTTP proxy URL | +| 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)_
`forge.s3.accessKeyId` - Your access key for your AWS account _(falls back to the standard `AWS_ACCESS_KEY_ID` environment variable)_
`forge.s3.bucket` - The name of the S3 bucket to upload to
`forge.s3.folder` - The folder path to upload to inside your bucket, defaults to your application version
`forge.s3.public` - Whether to make the S3 upload public, defaults to `false` | +| [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
`forge.electronReleaseServer.username` - The username for the admin panel on your server
`forge.electronReleaseServer.password` - The password for the admin panel on your server
`forge.electronReleaseServer.channel` - If specified, the release channel name. Defaults to `stable`/`alpha`/`beta` depending on the app version | +| [Snapcraft](https://snapcraft.io/store/) - `snapStore` | Uploads generated Snaps to the Snap Store. | `forge.snapStore.release` - If specified, a comma-separated list of channels to release to. | + +For example: ```javascript +// github +{ + // Assume the GitHub repository is at https://github.com/username/repo + "github_repository": { + "owner": "username", + "name": "repo" + } +} + +// s3 { - "message": "Ain't no cake like that." + "s3": { + "accessKeyId": "", + "bucket": "my_bucket_name", + "public": true + } +} + +// Electron Release Server +{ + "electronReleaseServer": { + "baseUrl": "https://update.mysite.com", + "username": "admin", + "password": "no_one_will_guess_this" + } +} + +// Snap Store +{ + "snapStore": { + "release": "candidate,beta" + } } ``` -{% endapi-method-response-example %} -{% endapi-method-response %} -{% endapi-method-spec %} -{% endapi-method %} +## 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}`, they can be added to the app's +`devDependencies` and can be specified as `{name}` in the make / publish targets. Publicly published +third-party [makers](https://www.npmjs.com/search?q=electron%2Dforge%2Dmaker) and +[publishers](https://www.npmjs.com/search?q=electron-forge-publisher) are available in the NPM registry. + +The API for each target type 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 keyword parameters: +* `dir` - The application directory +* `artifacts` - An array of absolute paths to artifacts to publish +* `packageJSON` - An object representing the user's `package.json` file +* `forgeConfig` - An object representing the user's [`forgeConfig`](#config) +* `authToken` - The value of `--auth-token` +* `tag` - The value of `--tag` +* `platform` - The platform you are publishing for +* `arch` - The arch you are publishing for +You should use `ora` to indicate your publish progress. + +## Debugging your application on the command line + +If you're using Electron 1.7 or later, you can specify the `--inspect-electron` flag, which will +set the [Electron `--inspect` flag](http://electronjs.org/docs/tutorial/debugging-main-process#--inspectport) +with the default debugger port. + +For example: + +```shell +electron-forge start --inspect-electron +``` + +## Debugging your application through VS Code + +Debugging your Electron main process through VS Code is ridiculously +easy with Forge. Simply add this as a launch config in VSCode and you're +good to go. + +```js +{ + "type": "node", + "request": "launch", + "name": "Electron Main", + "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-forge-vscode-nix", + "windows": { + "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-forge-vscode-win.cmd" + }, + // runtimeArgs will be passed directly to your Electron application + "runtimeArgs": [ + "foo", + "bar" + ], + "cwd": "${workspaceRoot}" +} +``` diff --git a/SUMMARY.md b/SUMMARY.md deleted file mode 100644 index 41d4a3ddda..0000000000 --- a/SUMMARY.md +++ /dev/null @@ -1,6 +0,0 @@ -# Table of contents - -* [Initial page](README.md) -* ds -* [Untitled](untitled.md) - diff --git a/untitled.md b/untitled.md deleted file mode 100644 index 1e3902a87c..0000000000 --- a/untitled.md +++ /dev/null @@ -1,23 +0,0 @@ -# Untitled - -## Getting Super Powers - -Becoming a super hero is a fairly straight forward process: - -``` -$ give me super-powers -``` - -{% hint style="info" %} - Super-powers are granted randomly so please submit an issue if you're not happy with yours. -{% endhint %} - -Once you're strong enough, save the world: - -``` -// Ain't no code for that yet, sorry -echo 'You got to trust me on this, I saved the world' -``` - - -