GITBOOK-190: Document forge config transpilation

Author: erickzhao

SUMMARY.md

@@ -12,6 +12,7 @@
 ## Configuration <a href="#config" id="config"></a>
 
 * [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)

config/publishers/bitbucket.md

@@ -1,21 +1,19 @@
-# Bitbucket
+---
+description: >-
+  The Bitbucket publish target allows you to publish your artifacts directly to
+  Bitbucket where users will be able to download them.
+---
 
-The Bitbucket publish target allows you to publish your artifacts directly to Bitbucket where users will be able to download them.
+# Bitbucket
 
 {% 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 %}
 
-## Installation
-
-```bash
-npm install --save-dev @electron-forge/publisher-bitbucket
-```
+Full configuration options are documented in [`PublisherBitbucketConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_bitbucket.PublisherBitbucketConfig.html).
 
 ## 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 = {
@@ -39,7 +37,18 @@ module.exports = {
 ```
 {% endcode %}
 
-Full configuration options are documented in [`PublisherBitbucketConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_bitbucket.PublisherBitbucketConfig.html).
+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
+```
 
 {% hint style="info" %}
 Your artifacts can be found under the `Downloads` tab of your Bitbucket repository.

config/publishers/electron-release-server.md

@@ -4,15 +4,9 @@ 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.
 
-## Installation
-
-```bash
-npm install --save-dev @electron-forge/publisher-electron-release-server
-```
-
-## Usage
+Configuration options are documented in [`PublisherERSConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_electron\_release\_server.PublisherERSConfig.html).
 
-To use `@electron-forge/publisher-electron-release-server`, add it to the `publishers` array in your [Forge configuration](../configuration.md):
+### Usage
 
 {% code title="forge.config.js" %}
 ```javascript
@@ -31,5 +25,3 @@ module.exports = {
 };
 ```
 {% endcode %}
-
-Configuration options are documented in [`PublisherERSConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_electron\_release\_server.PublisherERSConfig.html).

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).
 
-## Installation
+## Authentication
 
-```bash
-npm install --save-dev @electron-forge/publisher-gcs
-```
+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.
 
 ## Usage
 
-To use `@electron-forge/publisher-gcs`, add it to the `publishers` array in your [Forge configuration](../configuration.md):
+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.
 
 {% code title="forge.config.js" %}
 ```javascript
@@ -42,24 +42,14 @@ 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.

config/publishers/github.md

@@ -1,17 +1,15 @@
 # GitHub
 
-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.
+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.
 
-## Installation
+Configuration options are documented in [`PublisherGitHubConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_github.PublisherGitHubConfig.html)
 
-```bash
-npm install --save-dev @electron-forge/publisher-github
-```
+{% 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 %}
 
 ## 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 = {
@@ -32,12 +30,6 @@ 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.

config/publishers/nucleus.md

@@ -2,16 +2,14 @@
 
 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.
 
-## Installation
+Configuration options are documented in [`PublisherNucleusConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_nucleus.PublisherNucleusConfig.html)
 
-```bash
-npm install --save-dev @electron-forge/publisher-nucleus
-```
+{% hint style="warning" %}
+We recommend you set the `token` option using an environment variable, don't hard code it into your config
+{% endhint %}
 
 ## 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 = {
@@ -30,5 +28,3 @@ module.exports = {
 };
 ```
 {% endcode %}
-
-Configuration options are documented in [`PublisherNucleusConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_nucleus.PublisherNucleusConfig.html).

config/publishers/s3.md

@@ -6,15 +6,13 @@ description: How to publish your distributable Electron app artifacts to Amazon
 
 The S3 target publishes your Make artifacts to an Amazon S3 bucket.
 
-## Installation
+## Authentication
 
-```bash
-npm install --save-dev @electron-forge/publisher-s3
-```
+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.
 
 ## Usage
 
-To use `@electron-forge/publisher-s3`, add it to the `publishers` array in your [Forge configuration](../configuration.md):
+Configuration options are documented in [`PublisherS3Config`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_s3.PublisherS3Config.html).
 
 {% code title="forge.config.js" %}
 ```javascript
@@ -33,12 +31,6 @@ 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:

config/publishers/snapcraft.md

@@ -1,20 +1,12 @@
 # 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.md](../makers/snapcraft.md "mention") maker.
+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).
 
-## Requirements
+This target requires that the system has the `snapcraft` utility installed.
 
-You can only publish to the Snap Store on Linux systems with the [`snapcraft`](https://snapcraft.io/) package installed.
+Configuration options are documented in [`PublisherSnapConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_snapcraft.PublisherSnapcraftConfig.html)
 
-## 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):
+### Usage
 
 {% code title="forge.config.js" %}
 ```javascript
@@ -31,5 +23,3 @@ module.exports = {
 };
 ```
 {% endcode %}
-
-Configuration options are documented in [`PublisherSnapConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_snapcraft.PublisherSnapcraftConfig.html).

config/typescript-configuration.md

@@ -0,0 +1,87 @@
+---
+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 %}

core-concepts/why-electron-forge.md

@@ -28,19 +28,9 @@ 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.
-
-
-
-
-
-
-
-
-
-##