diff --git a/SUMMARY.md b/SUMMARY.md index 60f4073..e3d8eb3 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -29,7 +29,7 @@ * [Snapcraft](config/makers/snapcraft.md) * [Squirrel.Windows](config/makers/squirrel.windows.md) * [WiX MSI](config/makers/wix-msi.md) - * [Zip](config/makers/zip.md) + * [ZIP](config/makers/zip.md) * [Publishers](config/publishers/README.md) * [Bitbucket](config/publishers/bitbucket.md) * [Electron Release Server](config/publishers/electron-release-server.md) diff --git a/config/makers/appx.md b/config/makers/appx.md index 468de7b..16a0727 100644 --- a/config/makers/appx.md +++ b/config/makers/appx.md @@ -1,25 +1,46 @@ --- description: >- - Create a package for the Windows Store for your Electron app, using Electron + Create a package for the Microsoft Store for your Electron app, using Electron Forge. --- # AppX -The AppX target builds `.appx` packages which are designed to target the Windows Store. You can only build the AppX target on Windows machines with the Windows 10 SDK installed. Check the [`electron-windows-store` docs](https://github.com/felixrieseberg/electron-windows-store#readme) for more information on platform requirements. +The AppX target builds `.appx` packages which are designed to target the [Microsoft Store](https://apps.microsoft.com/home). -Configuration options are documented in [`MakerAppXConfig`](https://js.electronforge.io/interfaces/_electron_forge_maker_appx.MakerAppXConfig.html). +### Requirements + +You can only build the AppX target on Windows 10 or 11 machines with the [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) installed. Check the [`electron-windows-store` docs](https://github.com/electron-userland/electron-windows-store) for more information on platform requirements. + +### Installation + +```bash +npm install --save-dev @electron-forge/maker-appx +``` ### Usage +To use `@electron-forge/maker-appx`, add it to the `makers` array in your [Forge configuration](../configuration.md): + +{% code title="forge.config.js" %} ```javascript -{ - name: '@electron-forge/maker-appx', - config: { - publisher: 'CN=developmentca', - devCert: 'C:\\devcert.pfx', - certPass: 'abcd' - } +module.exports = { + makers: [ + { + name: '@electron-forge/maker-appx', + config: { + publisher: 'CN=developmentca', + devCert: 'C:\\devcert.pfx', + certPass: 'abcd' + } + } + ] } ``` +{% endcode %} + +Configuration options are documented in [`MakerAppXConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_appx.MakerAppXConfig.html). + +### Debugging +For advanced debug logging for this maker, add the `DEBUG=electron-windows-store*` environment variable. diff --git a/config/makers/deb.md b/config/makers/deb.md index 47bee8e..42c0a94 100644 --- a/config/makers/deb.md +++ b/config/makers/deb.md @@ -6,21 +6,42 @@ description: >- # deb -The deb target builds [`.deb` packages](https://en.wikipedia.org/wiki/Deb_%28file_format%29), which are the standard package format for Debian-based Linux distributions such as Ubuntu. You can only build the deb target on Linux or macOS machines with the `fakeroot` and `dpkg` packages installed. +The deb target builds [`.deb` packages](https://www.debian.org/doc/manuals/debian-faq/pkg-basics.en.html), which are the standard package format for Debian-based Linux distributions such as [Ubuntu](https://ubuntu.com/). -Configuration options are documented in [`MakerDebConfig`](https://js.electronforge.io/interfaces/_electron_forge_maker_deb.MakerDebConfig.html). +### Requirements + +You can only build the deb target on Linux or macOS machines with the [`fakeroot`](https://wiki.debian.org/FakeRoot) and [`dpkg`](https://wiki.debian.org/dpkg) packages installed. + +### Installation + +```bash +npm install --save-dev @electron-forge/maker-deb +``` ### Usage +To use `@electron-forge/maker-deb`, add it to the `makers` array in your [Forge configuration](../configuration.md): + +{% code title="forge.config.js" %} ```javascript -{ - name: '@electron-forge/maker-deb', - config: { - options: { - maintainer: 'Joe Bloggs', - homepage: 'https://example.com' +module.exports = { + makers: [ + { + name: '@electron-forge/maker-deb', + config: { + options: { + maintainer: 'Joe Bloggs', + homepage: 'https://example.com' + } + } } - } + ] } ``` +{% endcode %} + +Configuration options are documented in [`MakerDebConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_deb.MakerDebConfig.html). + +### Debugging +For advanced debug logging for this maker, add the `DEBUG=electron-installer-deb*` environment variable. diff --git a/config/makers/dmg.md b/config/makers/dmg.md index ce714e8..b470627 100644 --- a/config/makers/dmg.md +++ b/config/makers/dmg.md @@ -4,25 +4,40 @@ description: Generate a DMG with Electron Forge to distribute your Electron app # DMG -The DMG target builds `.dmg` files, which are the standard format for sharing macOS apps. The DMG acts like a zip file, but provides an easy way for users to take the app and put it in the `/Applications` directory. +The DMG target builds Apple Disk Image (`.dmg`) files, which are the standard format for sharing macOS apps. The DMG acts like a ZIP file, but provides an easy way for users to take the app and put it in the `/Applications` directory. + +### Requirements -{% hint style="warning" %} You can only build the DMG target on macOS machines. -{% endhint %} -Configuration options are documented in [`MakerDMGConfig`](https://js.electronforge.io/interfaces/_electron_forge_maker_dmg.MakerDMGConfig.html). +### Installation + +```sh +npm install --save-dev @electron-forge/maker-dmg +``` ### Usage +To use `@electron-forge/maker-dmg`, add it to the `makers` array in your [Forge configuration](../configuration.md): + +{% code title="forge.config.js" %} ```javascript -{ - name: '@electron-forge/maker-dmg', - config: { - background: './assets/dmg-background.png', - format: 'ULFO' - } +module.exports = { + makers: [ + { + name: '@electron-forge/maker-dmg', + config: { + background: './assets/dmg-background.png', + format: 'ULFO' + } + } + ] } ``` +{% endcode %} +Configuration options are documented in [`MakerDMGConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_dmg.MakerDMGConfig.html). +### Debugging +For advanced debug logging for this maker, add the `DEBUG=electron-installer-dmg*` environment variable. diff --git a/config/makers/flatpak.md b/config/makers/flatpak.md index 76f26b1..65dcc8d 100644 --- a/config/makers/flatpak.md +++ b/config/makers/flatpak.md @@ -4,23 +4,40 @@ description: Create a Flatpak app for your Electron app using Electron Forge. # Flatpak -The Flatpak target builds [`.flatpak` files](http://flatpak.org/), which is a packaging format for Linux distributions that allows for sandboxed installation of applications in isolation from the rest of their system. In contrast, typical deb or RPM installation methods are not sandboxed. +The Flatpak target builds [`.flatpak` files](http://flatpak.org/), which is a packaging format for Linux distributions that allows for sandboxed installation of applications in isolation from the rest of their system. In contrast, typical [deb.md](deb.md "mention") or [rpm.md](rpm.md "mention") installation methods are not sandboxed. -You can only build the Flatpak target if you have `flatpak`, `flatpak-builder`, and `eu-strip` _\(usually part of the `elfutils` package\)_ installed on your system. +### Requirements -Configuration options are documented in [`MakerFlatpakConfig`](https://js.electronforge.io/classes/_electron_forge_maker_flatpak.MakerFlatpak-1.html#config). +You can only build the Flatpak target if you have [`flatpak`](https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak), [`flatpak-builder`](https://docs.flatpak.org/en/latest/flatpak-builder-command-reference.html#flatpak-builder), and `eu-strip` _(usually part of the_ [_`elfutils`_](https://sourceware.org/elfutils/) _package)_ installed on your system. + +### Installation + +```sh +npm install --save-dev @electron-forge/maker-flatpak +``` ### Usage +To use `@electron-forge/maker-flatpak`, add it to the `makers` array in your [Forge configuration](../configuration.md): + ```javascript -{ - name: '@electron-forge/maker-flatpak', - config: { - options: { - categories: ['Video'], - mimeType: ['video/h264'] +module.exports = { + makers: [ + { + name: '@electron-forge/maker-flatpak', + config: { + options: { + categories: ['Video'], + mimeType: ['video/h264'] + } + } } - } + ] } ``` +Configuration options are documented in [`MakerFlatpakConfig`](https://js.electronforge.io/classes/\_electron\_forge\_maker\_flatpak.MakerFlatpak-1.html#config). + +### Debugging + +For advanced debug logging for this maker, add the `DEBUG=electron-installer-flatpak*` environment variable. diff --git a/config/makers/pkg.md b/config/makers/pkg.md index f3a0282..10a3625 100644 --- a/config/makers/pkg.md +++ b/config/makers/pkg.md @@ -15,30 +15,39 @@ The flat installer package format is sparsely documented by Apple. If you want t * [Flat Package Format - The missing documentation](http://s.sudre.free.fr/Stuff/Ivanhoe/FLAT.html) (Stéphane Sudre) * [The Flat Package - Examining a newer package format](https://preserve.mactech.com/articles/mactech/Vol.26/26.02/TheFlatPackage/index.html) (MacTech) -## Usage +### Requirements -{% hint style="warning" %} You can only build the pkg target on macOS machines while targeting the `darwin` or `mas` platforms. -{% endhint %} -To use `@electron-forge/maker-pkg`, add it to the `makers` array in your Forge configuration. +### Installation -
module.exports = {
+```bash
+npm install --save-dev @electron-forge/maker-pkg
+```
+
+### Usage
+
+To use `@electron-forge/maker-pkg`, add it to the `makers` array in your [Forge configuration](../configuration.md):
+
+{% code title="forge.config.js" %}
+```javascript
+module.exports = {
   makers: [
-    {
-      name: '@electron-forge/maker-pkg',
-      config: {
-        keychain: 'my-secret-ci-keychain'
-        // other configuration options
-      }
-    }
-  ]
+    {
+      name: '@electron-forge/maker-pkg',
+      config: {
+        keychain: 'my-secret-ci-keychain'
+        // other configuration options
+      }
+    }
+  ]
 };
-
+``` +{% endcode %} All configuration options are optional, and options are documented in the API docs for [`MakerPkgConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_pkg.MakerPKGConfig.html). -### Installation scripts +### Adding installation scripts With the pkg maker, you can add either a `preinstall` or `postinstall` bash script that runs before and after your app is installed, respectively. @@ -75,8 +84,8 @@ module.exports = { -## Debugging +### Debugging All logs for your flat package installer can be found in macOS installation logs, which are stored in `/var/log/install.log`. They are also accessible within the [Console.app](https://support.apple.com/en-ca/guide/console/welcome/mac) utility. -For advanced debug logging for this maker, add the `DEBUG=electron-osx-sign` environment variable. +For advanced debug logging for this maker, add the `DEBUG=electron-osx-sign*` environment variable. diff --git a/config/makers/rpm.md b/config/makers/rpm.md index abf5a44..b963b0b 100644 --- a/config/makers/rpm.md +++ b/config/makers/rpm.md @@ -6,9 +6,9 @@ description: >- # RPM -The RPM target builds `.rpm` files, which is the standard package format for Red Hat-based Linux distributions such as Fedora and Red Hat Enterprise Linux (RHEL). +The RPM target builds `.rpm` files, which is the standard package format for Red Hat-based Linux distributions such as [Fedora](https://fedoraproject.org/) and [Red Hat Enterprise Linux](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) (RHEL). -## Requirements +### Requirements You can only build the RPM target on Linux machines with the `rpm` or `rpm-build` packages installed. @@ -24,17 +24,35 @@ While on Debian or Ubuntu you'll need to do this: sudo apt-get install rpm ``` -## Usage +### Installation -Configuration options are documented in [`MakerRpmConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_rpm.MakerRpmConfig.html). +```shell +npm install --save-dev @electron-forge/maker-rpm +``` + +### Usage + +To use `@electron-forge/maker-rpm`, add it to the `makers` array in your [Forge configuration](../configuration.md): +{% code title="forge.config.js" %} ```javascript -{ - name: '@electron-forge/maker-rpm', - config: { - options: { - homepage: 'http://example.com' +module.exports = { + makers: [ + { + name: '@electron-forge/maker-rpm', + config: { + options: { + homepage: 'http://example.com' + } + } } - } + ] } ``` +{% endcode %} + +Configuration options are documented in [`MakerRpmConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_rpm.MakerRpmConfig.html). + +### Debugging + +For advanced debug logging for this maker, add the `DEBUG=electron-installer-redhat*` environment variable. diff --git a/config/makers/snapcraft.md b/config/makers/snapcraft.md index 28b2340..bcf2c28 100644 --- a/config/makers/snapcraft.md +++ b/config/makers/snapcraft.md @@ -4,25 +4,44 @@ description: Create a Snap package for your Electron app using Electron Forge. # Snapcraft -The Snapcraft target builds `.snap` files, which is the packaging format created and sponsored by Canonical, the company behind Ubuntu. It is a sandboxed package format that lets users of various Linux distributions install your application in an isolated environment on their machine. +The [Snapcraft](https://snapcraft.io/) target builds `.snap` files, which is the packaging format created and sponsored by Canonical, the company behind Ubuntu. It is a sandboxed package format that lets users of various Linux distributions install your application in an isolated environment on their machine. + +### Requirements You can only build the Snapcraft target on Linux systems with the [`snapcraft`](https://snapcraft.io/) package installed. -Configuration options are documented in [`MakerSnapConfig`](https://js.electronforge.io/modules/_electron_forge_maker_snap.html#MakerSnapConfig). +### Installation + +```bash +npm install --save-dev @electron-forge/maker-snap +``` + +### Usage -## Usage +To use `@electron-forge/maker-snap`, add it to the `makers` array in your [Forge configuration](../configuration.md): +{% code title="forge.config.js" %} ```javascript -{ - name: '@electron-forge/maker-snap', - config: { - features: { - audio: true, - mpris: 'com.example.mpris', - webgl: true - }, - summary: 'Pretty Awesome' - } +module.exports = { + makers: [ + { + name: '@electron-forge/maker-snap', + config: { + features: { + audio: true, + mpris: 'com.example.mpris', + webgl: true + }, + summary: 'Pretty Awesome' + } + } + ] } ``` +{% endcode %} + +Configuration options are documented in [`MakerSnapConfig`](https://js.electronforge.io/modules/\_electron\_forge\_maker\_snap.html#MakerSnapConfig). + +### Debugging +For advanced debug logging for this maker, add the `DEBUG=electron-installer-snap*` environment variable. diff --git a/config/makers/squirrel.windows.md b/config/makers/squirrel.windows.md index db2132a..2a37109 100644 --- a/config/makers/squirrel.windows.md +++ b/config/makers/squirrel.windows.md @@ -10,9 +10,17 @@ The Squirrel.Windows target builds your application using the [Squirrel.Windows] Squirrel.Windows is a no-prompt, no-hassle, no-admin method of installing Windows applications, and is therefore the most user friendly you can get. -You can only build the Squirrel.Windows target on a Windows machine or on a Linux machine with `mono` and `wine` installed. +### Requirements -## Usage +You can only build the Squirrel.Windows target on a Windows machine or on a Linux machine with [`mono`](https://www.mono-project.com/) and [`wine`](https://www.winehq.org/) installed. + +### Installation + +```bash +npm install --save-dev @electron-forge/maker-squirrel +``` + +### Usage Add this module to the [makers](./) section of your [Forge configuration](../configuration.md): @@ -32,8 +40,6 @@ module.exports = { ``` {% endcode %} -## Configuration - The Squirrel.Windows maker inherits all of its config options from the [`electron-winstaller`](https://github.com/electron/windows-installer) module, _except_ for `appDirectory` and `outputDirectory`, which are set by the maker. Complete configuration options are documented in the [`MakerSquirrelConfig`](https://js.electronforge.io/modules/\_electron\_forge\_maker\_squirrel.html#MakerSquirrelConfig) types. @@ -44,7 +50,7 @@ Squirrel.Windows requires mandatory package metadata to satisfy the [`.nuspec`]( #### In package.json -By default, the Squirrel.Windows maker fetches the `author` and `description` fields in the project's package.json file. +By default, the Squirrel.Windows maker fetches the `author` and `description` fields in the project's package.json file. {% code title="package.json" %} ```jsonc @@ -81,9 +87,9 @@ module.exports = { Note that the Forge config field is **"authors"** while the package.json field is called **"author".** {% endhint %} -## Handling startup events +### Handling startup events -When first running your app, updating it, and uninstalling it, Squirrel.Windows will spawn your app an additional time with some special arguments. You can read more about these arguments on the [`electron-winstaller`](https://github.com/electron/windows-installer) README. +When first running your app, updating it, and uninstalling it, Squirrel.Windows will spawn your app an additional time with some special arguments. You can read more about these arguments on the [`electron-winstaller`](https://github.com/electron/windows-installer) README. The easiest way to handle these arguments and stop your app launching multiple times during these events is to use the [`electron-squirrel-startup`](https://github.com/mongodb-js/electron-squirrel-startup) module as one of the first things your app does. @@ -95,3 +101,7 @@ const { app } = require('electron'); if (require('electron-squirrel-startup')) app.quit(); ``` {% endcode %} + +### Debugging + +For advanced debug logging for this maker, add the `DEBUG=electron-windows-installer*` environment variable. diff --git a/config/makers/wix-msi.md b/config/makers/wix-msi.md index 02c7c5b..8a849c9 100644 --- a/config/makers/wix-msi.md +++ b/config/makers/wix-msi.md @@ -4,21 +4,46 @@ description: Create an MSI file for your Electron app on Windows using Electron # WiX MSI -The WiX MSI target builds `.msi` files, which are "traditional" Windows installer files. Please note we recommend using the [Squirrel.Windows](squirrel.windows.md) target over using this one. These MSI files are a worse user experience for installation but sometimes it is necessary to build MSI files to appease large scale enterprise companies with internal application distribution policies. For more info, check out "[Should I use WiX MSI?](https://github.com/felixrieseberg/electron-wix-msi#should-i-use-this)". +The WiX MSI target builds `.msi` files, which are "traditional" Windows installer files. -You can only build the WiX MSI target on machines with [`light` and `candle` installed from the WiX toolkit](https://github.com/felixrieseberg/electron-wix-msi#prerequisites). +{% hint style="warning" %} +We generally recommend using the [squirrel.windows.md](squirrel.windows.md "mention") target over using this one. These MSI files are a worse user experience for installation but sometimes it is necessary to build MSI files to appease large-scale enterprise companies with internal application distribution policies. +{% endhint %} -Configuration options are documented in [`MakerWixConfig`](https://js.electronforge.io/interfaces/_electron_forge_maker_wix.MakerWixConfig.html). +### Requirements + +You can only build the WiX MSI target on machines with [WiX Toolset v3](https://wixtoolset.org/docs/wix3/) installed. We recommend pinning your installation of WiX Toolset to a specific version. You can install WiX Toolset on Windows via [Chocolatey](https://chocolatey.org/). + +```bash +choco install wixtoolset --version=3.14.0 +``` + +### Installation + +```bash +npm install --save-dev @electron-forge/maker-wix +``` ### Usage +To use `@electron-forge/maker-wix`, add it to the `makers` array in your [Forge configuration](../configuration.md): + ```javascript -{ - name: '@electron-forge/maker-wix', - config: { - language: 1033, - manufacturer: 'My Awesome Company' - } +module.exports = { + makers: [ + { + name: '@electron-forge/maker-wix', + config: { + language: 1033, + manufacturer: 'My Awesome Company' + } + } + ] } ``` +Configuration options are documented in [`MakerWixConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_wix.MakerWixConfig.html). + +### Debugging + +For advanced debug logging for this maker, add the `DEBUG=electron-wix-msi*` environment variable. diff --git a/config/makers/zip.md b/config/makers/zip.md index 2e28c55..026efd9 100644 --- a/config/makers/zip.md +++ b/config/makers/zip.md @@ -4,9 +4,15 @@ description: Create a ZIP archive for your Electron app using Electron Forge. # ZIP -The ZIP target builds basic [.zip archives](https://en.wikipedia.org/wiki/ZIP_(file_format)) containing your packaged application. There are no platform-specific dependencies for using this maker and it will run on any platform. +The ZIP target builds basic [.zip archives](https://en.wikipedia.org/wiki/ZIP\_\(file\_format\)) containing your packaged application. There are no platform-specific dependencies for using this maker and it will run on any platform. -## Usage +### Installation + +```bash +npm install --save-dev @electron-forge/maker-zip +``` + +### Usage To use `@electron-forge/maker-zip`, add it to the `makers` array in your Forge configuration. @@ -22,7 +28,7 @@ module.exports = { ``` {% endcode %} -All configuration options are optional, and options are documented in the API docs for [MakerZIPConfig](https://js.electronforge.io/interfaces/_electron_forge_maker_zip.MakerZIPConfig.html). +All configuration options are optional, and options are documented in the API docs for [MakerZIPConfig](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_zip.MakerZIPConfig.html). ### Static file auto-updates (macOS) @@ -68,4 +74,4 @@ The first time you run `make` with this parameter configured, an architecture-sp Once this asset is uploaded to the bucket, subsequent runs will read from the existing manifest at `https://my-bucket.s3.amazonaws.com/my-app-updates/darwin/arm64/RELEASES.json` and modify it to update the `currentRelease` property to the next version that is built. -For end-to-end instructions on this process, including how to publish assets to S3 and set up the autoUpdater to read the `RELEASES.json` manifest, see the [Auto updating from S3](../publishers/s3.md#auto-updating-from-s3 "mention") guide. +For end-to-end instructions on this process, including how to publish assets to S3 and set up the autoUpdater to read the `RELEASES.json` manifest, see the [#auto-updating-from-s3](../publishers/s3.md#auto-updating-from-s3 "mention") guide.