diff --git a/SUMMARY.md b/SUMMARY.md index d0fa39e..e3d8eb3 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -12,7 +12,6 @@ ## Configuration * [Overview](config/configuration.md) -* [TypeScript Configuration](config/typescript-configuration.md) * [Plugins](config/plugins/README.md) * [Webpack Plugin](config/plugins/webpack.md) * [Vite Plugin](config/plugins/vite.md) diff --git a/config/publishers/bitbucket.md b/config/publishers/bitbucket.md index 29fa5d5..b06f0e0 100644 --- a/config/publishers/bitbucket.md +++ b/config/publishers/bitbucket.md @@ -1,19 +1,21 @@ ---- -description: >- - The Bitbucket publish target allows you to publish your artifacts directly to - Bitbucket where users will be able to download them. ---- - # Bitbucket +The Bitbucket publish target allows you to publish your artifacts directly to Bitbucket where users will be able to download them. + {% hint style="warning" %} This publish target is for [Bitbucket Cloud](https://bitbucket.org) only and will not work with self hosted Bitbucket Server instances. {% endhint %} -Full configuration options are documented in [`PublisherBitbucketConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_bitbucket.PublisherBitbucketConfig.html). +## Installation + +```bash +npm install --save-dev @electron-forge/publisher-bitbucket +``` ## Usage +To use `@electron-forge/publisher-bitbucket`, add it to the `publishers` array in your [Forge configuration](../configuration.md): + {% code title="forge.config.js" %} ```javascript module.exports = { @@ -37,18 +39,7 @@ module.exports = { ``` {% endcode %} -you can (and should) use environment variables for the authentication - -{% code title="env.sh" %} -```bash -BITBUCKET_USERNAME="myusername" -BITBUCKET_APP_PASSWORD="mysecretapppassword" -``` -{% endcode %} - -```bash -$ source env.sh -``` +Full configuration options are documented in [`PublisherBitbucketConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_bitbucket.PublisherBitbucketConfig.html). {% hint style="info" %} Your artifacts can be found under the `Downloads` tab of your Bitbucket repository. diff --git a/config/publishers/electron-release-server.md b/config/publishers/electron-release-server.md index 072a25c..0460dda 100644 --- a/config/publishers/electron-release-server.md +++ b/config/publishers/electron-release-server.md @@ -4,9 +4,15 @@ The Electron Release Server target publishes all your artifacts to a hosted inst Please note that Electron Release Server is a community powered project and is not associated with Electron Forge or the Electron project directly. -Configuration options are documented in [`PublisherERSConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_electron\_release\_server.PublisherERSConfig.html). +## Installation + +```bash +npm install --save-dev @electron-forge/publisher-electron-release-server +``` -### Usage +## Usage + +To use `@electron-forge/publisher-electron-release-server`, add it to the `publishers` array in your [Forge configuration](../configuration.md): {% code title="forge.config.js" %} ```javascript @@ -25,3 +31,5 @@ module.exports = { }; ``` {% endcode %} + +Configuration options are documented in [`PublisherERSConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_electron\_release\_server.PublisherERSConfig.html). diff --git a/config/publishers/gcs.md b/config/publishers/gcs.md index 3ac679b..ce1dd27 100644 --- a/config/publishers/gcs.md +++ b/config/publishers/gcs.md @@ -10,15 +10,15 @@ This Publisher was added in Electron Forge **v7.1.0**. The Google Cloud Storage target publishes all your artifacts to a [Google Cloud Storage bucket](https://cloud.google.com/storage/docs). -## Authentication +## Installation -Under the hood, the Google Cloud Storage Publisher uses the `@google-cloud/storage` SDK and its associated authentication options. - -We recommend following [Google's authentication documentation for client libraries](https://cloud.google.com/docs/authentication/client-libraries#node.js) to get authentication configured. +```bash +npm install --save-dev @electron-forge/publisher-gcs +``` ## Usage -To pass options into the Google Cloud Storage SDK's [Storage constructor](https://cloud.google.com/nodejs/docs/reference/storage/latest/storage/storageoptions), use the `config.storageOptions` parameter. +To use `@electron-forge/publisher-gcs`, add it to the `publishers` array in your [Forge configuration](../configuration.md): {% code title="forge.config.js" %} ```javascript @@ -42,14 +42,24 @@ module.exports = { ``` {% endcode %} +Additional configuration options are documented in [`PublisherGCSConfig`](http://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_gcs.PublisherGCSConfig.html). + +To pass options into the Google Cloud Storage SDK's [Storage constructor](https://cloud.google.com/nodejs/docs/reference/storage/latest/storage/storageoptions), use the `config.storageOptions` parameter. + +### Output location + When executed, the Publisher will publish to your GCS bucket under the following key: ``` ${config.folder || version}/${artifactName} ``` -Additional configuration options are documented in [`PublisherGCSConfig`](http://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_gcs.PublisherGCSConfig.html). - {% hint style="warning" %} If you run publish twice with the same version on the same platform, it is possible for your old artifacts to get overwritten in Storage. It is your responsibility to ensure that you don't overwrite your own releases. {% endhint %} + +### Authentication + +Under the hood, the Google Cloud Storage Publisher uses the `@google-cloud/storage` SDK and its associated authentication options. + +We recommend following [Google's authentication documentation for client libraries](https://cloud.google.com/docs/authentication/client-libraries#node.js) to get authentication configured. diff --git a/config/publishers/github.md b/config/publishers/github.md index 7d2bbe4..5031eac 100644 --- a/config/publishers/github.md +++ b/config/publishers/github.md @@ -1,15 +1,17 @@ # GitHub -The GitHub target publishes all your artifacts to GitHub releases, this allows your users to download the files straight from your repository or if your repository is open source you can use [update.electronjs.org](https://github.com/electron/update.electronjs.org) and get a free hosted update service. +The GitHub target publishes all your artifacts to GitHub releases, this allows your users to download the files straight from your repository. If your repository is open source you can use [update.electronjs.org](https://github.com/electron/update.electronjs.org) and get a free hosted update service. -Configuration options are documented in [`PublisherGitHubConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_github.PublisherGitHubConfig.html) +## Installation -{% hint style="info" %} -You can use this target to publish to GitHub Enterprise using the host configuration options of `octokitOptions`. Check out the configuration options linked above. -{% endhint %} +```bash +npm install --save-dev @electron-forge/publisher-github +``` ## Usage +To use `@electron-forge/publisher-github`, add it to the `publishers` array in your [Forge configuration](../configuration.md): + {% code title="forge.config.js" %} ```javascript module.exports = { @@ -30,6 +32,12 @@ module.exports = { ``` {% endcode %} +Configuration options are documented in [`PublisherGitHubConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_github.PublisherGitHubConfig.html). + +### Uploading to GitHub Enterprise instances + +You can use this target to publish to GitHub Enterprise using the host configuration options of `octokitOptions`. Check out the configuration options linked above. + ### Auto updating from GitHub Updating from a GitHub release for a **public** repository is as simple as adding the [`update-electron-app`](https://github.com/electron/update-electron-app) module to your app's main process. diff --git a/config/publishers/nucleus.md b/config/publishers/nucleus.md index 0213e02..aad13b6 100644 --- a/config/publishers/nucleus.md +++ b/config/publishers/nucleus.md @@ -2,14 +2,16 @@ The Nucleus target publishes all your artifacts to an instance of Nucleus Update Server, this update service supports all three platforms. Check out the README at [`atlassian/nucleus`](https://github.com/atlassian/nucleus) for more information on this project. -Configuration options are documented in [`PublisherNucleusConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_nucleus.PublisherNucleusConfig.html) +## Installation -{% hint style="warning" %} -We recommend you set the `token` option using an environment variable, don't hard code it into your config -{% endhint %} +```bash +npm install --save-dev @electron-forge/publisher-nucleus +``` ## Usage +To use `@electron-forge/publisher-nucleus`, add it to the `publishers` array in your [Forge configuration](../configuration.md): + {% code title="forge.config.js" %} ```javascript module.exports = { @@ -28,3 +30,5 @@ module.exports = { }; ``` {% endcode %} + +Configuration options are documented in [`PublisherNucleusConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_nucleus.PublisherNucleusConfig.html). diff --git a/config/publishers/s3.md b/config/publishers/s3.md index e89c070..0bd73ca 100644 --- a/config/publishers/s3.md +++ b/config/publishers/s3.md @@ -6,13 +6,15 @@ description: How to publish your distributable Electron app artifacts to Amazon The S3 target publishes your Make artifacts to an Amazon S3 bucket. -## Authentication +## Installation -It is recommended to follow the [Amazon AWS guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html) and set either a shared credentials guide or the proper environment variables. However, if that is not possible, the publisher config allows the setting of the `accessKeyId` and `secretAccessKey` configuration options. +```bash +npm install --save-dev @electron-forge/publisher-s3 +``` ## Usage -Configuration options are documented in [`PublisherS3Config`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_s3.PublisherS3Config.html). +To use `@electron-forge/publisher-s3`, add it to the `publishers` array in your [Forge configuration](../configuration.md): {% code title="forge.config.js" %} ```javascript @@ -31,6 +33,12 @@ module.exports = { ``` {% endcode %} +Configuration options are documented in [`PublisherS3Config`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_s3.PublisherS3Config.html). + +### Authentication + +It is recommended to follow the [Amazon AWS guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html) and set either a shared credentials guide or the proper environment variables. However, if that is not possible, the publisher config allows the setting of the `accessKeyId` and `secretAccessKey` configuration options. + ### Key management By default, the S3 publisher will upload its objects to the `{prefix}/{platform}/{arch}/{name}` key, where: diff --git a/config/publishers/snapcraft.md b/config/publishers/snapcraft.md index 6ceebef..160c7f2 100644 --- a/config/publishers/snapcraft.md +++ b/config/publishers/snapcraft.md @@ -1,12 +1,20 @@ # Snapcraft -The Snapcraft target publishes your `.snap` artifacts to the [Snap Store](https://snapcraft.io/store). All configuration of your package is done via the [Snapcraft maker](../makers/snapcraft.md). +The Snapcraft target publishes your `.snap` artifacts to the [Snap Store](https://snapcraft.io/store). All configuration of your package is done via the [snapcraft.md](../makers/snapcraft.md "mention") maker. -This target requires that the system has the `snapcraft` utility installed. +## Requirements -Configuration options are documented in [`PublisherSnapConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_snapcraft.PublisherSnapcraftConfig.html) +You can only publish to the Snap Store on Linux systems with the [`snapcraft`](https://snapcraft.io/) package installed. -### Usage +## Installation + +```bash +npm install --save-dev @electron-forge/publisher-snapcraft +``` + +## Usage + +To use `@electron-forge/publisher-snapcraft`, add it to the `publishers` array in your [Forge configuration](../configuration.md): {% code title="forge.config.js" %} ```javascript @@ -23,3 +31,5 @@ module.exports = { }; ``` {% endcode %} + +Configuration options are documented in [`PublisherSnapConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_snapcraft.PublisherSnapcraftConfig.html). diff --git a/config/typescript-configuration.md b/config/typescript-configuration.md deleted file mode 100644 index 9a2e19a..0000000 --- a/config/typescript-configuration.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -description: Set up your Forge configuration to use TypeScript ---- - -# TypeScript Configuration - -By default, Electron Forge's [configuration](broken-reference) only supports JavaScript and JSON files as inputs. - -Forge also supports configuration files in other languages that transpile down to JavaScript as long as a transpiler is installed locally in your project's `devDependencies`. These configuration files follow the same format as `forge.config.js`. - -## Installation - -For TypeScript, we recommend installing [`ts-node`](https://github.com/TypeStrong/ts-node). Upon installation, it will automatically be registered as a module loader for `.ts` files. - -```bash -npm install --save-dev ts-node -``` - -## Configuration file - -Once you have `ts-node` installed, Forge will be able to load a `forge.config.ts` file from your project's root directory. - -This config format is functionally identical to `forge.config.js`. - -{% code title="forge.config.ts" %} -```typescript -import type { ForgeConfig } from '@electron-forge/shared-types'; - -const config: ForgeConfig = { - packagerConfig: { - asar: true, - osxSign: {} - } - makers: [ - { - name: '@electron-forge/maker-squirrel', - platforms: ['win32'], - config: { - authors: "Electron contributors" - } - }, - { - name: '@electron-forge/maker-zip', - platforms: ['darwin'], - config: {} - }, - { - name: '@electron-forge/maker-deb', - platforms: ['linux'], - config: {} - }, - ] -}; - -export default config; -``` -{% endcode %} - -## Using module constructor syntax - -When using a TypeScript configuration file, you may want to have stronger type validation around the individual options for each Maker, Publisher, or Plugin. - -To achieve this, you can import each module's constructor, which accepts its config object as the first parameter and the list of target platforms as the second parameter. - -For example, the below configuration is equivalent to the `makers` array from the example above: - -{% code title="forge.config.ts" %} -```typescript -import type { ForgeConfig } from '@electron-forge/shared-types'; -import { MakerDeb } from '@electron-forge/maker-deb'; -import { MakerSquirrel } from '@electron-forge/maker-squirrel'; -import { MakerZIP } from '@electron-forge/maker-zip'; - -const config: ForgeConfig = { - makers: [ - new MakerSquirrel({ - authors: 'Electron contributors' - }, ['win32']), - new MakerZIP({}, ['darwin']), - new MakerDeb({}, ['linux']), - new MakerRpm({}, ['linux']), - ] -}; - -export default config; -``` -{% endcode %} diff --git a/core-concepts/why-electron-forge.md b/core-concepts/why-electron-forge.md index 59c42b6..f35e414 100644 --- a/core-concepts/why-electron-forge.md +++ b/core-concepts/why-electron-forge.md @@ -28,9 +28,19 @@ Forge is also built with advanced use cases in mind—you can add any build logi Electron Forge can be considered an alternative to [Electron Builder](https://electron.build/), which fulfills the same use-case for application building and publishing. -The key difference in philosophy between the two projects is that Electron Forge focuses on combining existing first-party tools into a single build pipeline, while Builder rewrites its own in-house logic for most build tasks. +The key difference in philosophy between the two projects is that Electron Forge focuses on combining existing first-party tools into a single build pipeline, while Builder rewrites its own in-house logic for most build tasks. We believe there are two main advantages to using Forge: 1. **Forge receives new features for application building as soon as they are supported in Electron** (e.g. [ASAR integrity](https://electronjs.org/docs/latest/tutorial/asar-integrity) or [universal macOS builds](https://github.com/electron/universal)). These features are built with first-party Electron tooling in mind, so Forge receives them as soon as they are released. 2. **Forge's multi-package architecture makes it easier to understand and extend.** Since Forge is made up of many smaller packages with clear responsibilities, it is easier to follow the flow of the code. Also, its extensible API design means that you can write your own build logic separate from the provided configuration options for advanced use cases. + + + + + + + + + +##