diff --git a/.gitbook/assets/Untitled-2022-08-26-1442.png b/.gitbook/assets/Untitled-2022-08-26-1442.png
deleted file mode 100644
index e638aef..0000000
Binary files a/.gitbook/assets/Untitled-2022-08-26-1442.png and /dev/null differ
diff --git a/.github/workflows/add-to-project.yml b/.github/workflows/add-to-project.yml
deleted file mode 100644
index 05903d8..0000000
--- a/.github/workflows/add-to-project.yml
+++ /dev/null
@@ -1,30 +0,0 @@
-name: Add to Ecosystem WG Project
-
-on:
- issues:
- types:
- - opened
- pull_request_target:
- types:
- - opened
-
-permissions: {}
-
-jobs:
- add-to-project:
- runs-on: ubuntu-latest
- steps:
- - name: Generate GitHub App token
- uses: electron/github-app-auth-action@384fd19694fe7b6dcc9a684746c6976ad78228ae # v1.1.1
- id: generate-token
- with:
- creds: ${{ secrets.ECOSYSTEM_ISSUE_TRIAGE_GH_APP_CREDS }}
- org: electron
- - name: Add to Project
- uses: dsanders11/project-actions/add-item@a24415515fa60a22f71f9d9d00e36ca82660cde9 # v1.0.1
- with:
- field: Opened
- field-value: ${{ github.event.pull_request.created_at || github.event.issue.created_at }}
- owner: electron
- project-number: 89
- token: ${{ steps.generate-token.outputs.token }}
diff --git a/.github/workflows/auto-fix-lint.yml b/.github/workflows/auto-fix-lint.yml
deleted file mode 100644
index 75a1aa3..0000000
--- a/.github/workflows/auto-fix-lint.yml
+++ /dev/null
@@ -1,52 +0,0 @@
-name: Auto-fix Lint
-
-on:
- push:
- branches:
- - v6
- - v7
- workflow_dispatch:
-
-permissions:
- contents: read
-
-jobs:
- build:
- runs-on: ubuntu-latest
- # Safeguard against creating a loop
- if: "${{ github.event.commits[0].message != 'chore: auto-fix lint' }}"
- steps:
- - name: Generate GitHub App token
- uses: electron/github-app-auth-action@384fd19694fe7b6dcc9a684746c6976ad78228ae # v1.1.1
- id: generate-token
- with:
- creds: ${{ secrets.GH_APP_CREDS }}
- export-git-user: true
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # tag: v4.1.1
- with:
- token: ${{ steps.generate-token.outputs.token }}
- - name: Setup Node.js
- uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # tag: v4.0.0
- with:
- node-version: lts/*
- - name: Create a Temporary package.json
- run: npm init --yes
- - name: Install @electron/lint-roller
- run: npm install --save-dev @electron/lint-roller
- - name: Run markdownlint
- run: npx electron-markdownlint --fix "**/*.md"
- - name: Lint JS in Markdown with standard
- run: npx electron-lint-markdown-standard --ignore-path .markdownlintignore --semi --fix "**/*.md"
- - name: Push Any Changes
- run: |
- rm -rf node_modules
- rm -f package.json
- rm -f package-lock.json
- git add .
- if test -n "$(git status -s)"; then
- git diff --cached
- git commit -m "chore: auto-fix lint"
- git push origin HEAD:$GITHUB_REF
- else
- echo No changes to push
- fi
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
deleted file mode 100644
index e95c4f1..0000000
--- a/.github/workflows/lint.yml
+++ /dev/null
@@ -1,40 +0,0 @@
-name: Lint
-
-on:
- push:
- pull_request:
- branches:
- - v6
- - v7
- workflow_dispatch:
- inputs:
- fetch-external-links:
- type: boolean
- description: Check if external links are broken
-
-permissions:
- contents: read
-
-jobs:
- build:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # tag: v4.1.1
- - name: Setup Node.js
- uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # tag: v4.0.0
- with:
- node-version: lts/*
- - name: Create a Temporary package.json
- run: npm init --yes
- - name: Install @electron/lint-roller
- run: npm install --save-dev @electron/lint-roller
- - name: Run markdownlint
- run: npx electron-markdownlint "**/*.md"
- - name: Lint JS in Markdown with standard
- run: npx electron-lint-markdown-standard --ignore-path .markdownlintignore --semi "**/*.md"
- - name: Lint links
- run: npx electron-lint-markdown-links --ignore-path .markdownlintignore "**/*.md"
- if: ${{ always() }}
- - name: Check external links
- run: npx electron-lint-markdown-links --ignore-path .markdownlintignore --fetch-external-links "**/*.md"
- if: ${{ github.event.inputs.fetch-external-links }}
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..44e6835
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,20 @@
+# Dependencies
+node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/.markdownlint.json b/.markdownlint.json
deleted file mode 100644
index f3caf86..0000000
--- a/.markdownlint.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "extends": "@electron/lint-roller/configs/markdownlint.json",
- "fenced-code-language": false,
- "blanks-around-fences": false,
- "no-multiple-blanks": false
-}
diff --git a/.markdownlintignore b/.markdownlintignore
deleted file mode 100644
index a860310..0000000
--- a/.markdownlintignore
+++ /dev/null
@@ -1 +0,0 @@
-node_modules/**
diff --git a/README.md b/README.md
index 84fa159..1ce63fc 100644
--- a/README.md
+++ b/README.md
@@ -12,9 +12,9 @@ Electron Forge is an all-in-one tool for packaging and distributing Electron app
To get started with Electron Forge, we first need to initialize a new project with `create-electron-app`. This script is a convenient wrapper around Forge's [Init](cli.md#Init) command.
-{% hint style="warning" %}
+:::warning
Electron Forge currently only supports npm and Yarn Classic. If you are using Yarn >=2, please use the `nodeLinker: node-modules` install mode.
-{% endhint %}
+:::
```bash
npm init electron-app@latest my-app
@@ -37,9 +37,9 @@ There are currently four first-party templates:
Both of these templates are built around plugins that bundle your JavaScript code for production and includes a dev server to provide a better developer experience.
-{% hint style="info" %}
+:::info
We highly recommend using these templates when initializing your app to take advantage of modern front-end JavaScript tooling.
-{% endhint %}
+:::
To learn more about authoring your own templates for Electron Forge, check out the [Writing Templates](advanced/extending-electron-forge/writing-templates.md) guide!
diff --git a/babel.config.js b/babel.config.js
new file mode 100644
index 0000000..e00595d
--- /dev/null
+++ b/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+ presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..1ce63fc
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,87 @@
+---
+description: Quickly scaffold an Electron project with a full build pipeline
+---
+
+# Getting Started
+
+## Overview
+
+Electron Forge is an all-in-one tool for packaging and distributing Electron applications. It combines many single-purpose packages to create a full build pipeline that works out of the box, complete with code signing, installers, and artifact publishing. For advanced workflows, custom build logic can be added in the Forge lifecycle through its [Plugin API](config/plugins/). Custom build and storage targets can be handled by creating your own [Makers](config/makers/) and [Publishers](config/publishers/).
+
+## Creating a new app
+
+To get started with Electron Forge, we first need to initialize a new project with `create-electron-app`. This script is a convenient wrapper around Forge's [Init](cli.md#Init) command.
+
+:::warning
+Electron Forge currently only supports npm and Yarn Classic. If you are using Yarn >=2, please use the `nodeLinker: node-modules` install mode.
+:::
+
+```bash
+npm init electron-app@latest my-app
+```
+
+### Using templates
+
+Forge's initialization scripts can add additional template code with the `--template=[template-name]` flag.
+
+```bash
+npm init electron-app@latest my-app -- --template=webpack
+```
+
+There are currently four first-party templates:
+
+* `webpack`
+* `webpack-typescript`
+* `vite`
+* `vite-typescript`
+
+Both of these templates are built around plugins that bundle your JavaScript code for production and includes a dev server to provide a better developer experience.
+
+:::info
+We highly recommend using these templates when initializing your app to take advantage of modern front-end JavaScript tooling.
+:::
+
+To learn more about authoring your own templates for Electron Forge, check out the [Writing Templates](advanced/extending-electron-forge/writing-templates.md) guide!
+
+## Starting your app
+
+You should now have a directory called `my-app` with all the files you need for a basic Electron app.
+
+```bash
+cd my-app
+npm start
+```
+
+## Building distributables
+
+So you've got an **amazing** application there, and you want to package it all up and share it with the world. If you run the `make` script, Electron Forge will generate you platform specific distributables for you to share with everyone. For more information on what kind of distributables you can make, check out the [Makers](config/makers/) documentation.
+
+```bash
+npm run make
+```
+
+## Publishing your app
+
+Now you have distributables that you can share with your users. If you run the `publish` script, Electron Forge will then publish the platform-specific distributables for you, using the publishing method of your choice. For example, if you want to publish your assets to GitHub, you can install the GitHub publisher dependency using:
+
+```bash
+npm install --save-dev @electron-forge/publisher-github
+```
+
+Once you have [configured the publisher according to the documentation](config/publishers/github), run the following command to upload your distributables:
+
+```bash
+npm run publish
+```
+
+For more information on what publishers we currently support, check out the [Publishers](config/publishers/) documentation.
+
+## Advanced Usage
+
+Once you've got a basic app starting, building and publishing, it's time to add your custom configuration, which can be done in the `forge.config.js` file. Configuration options are specified in the [Configuration Docs](https://www.electronforge.io/configuration).
+
+You can also check out the documentation on some of our more advanced features like:
+
+* [Adding plugins](config/plugins/)
+* [Debugging your app](advanced/debugging.md)
+* [Writing your own makers, publishers and plugins](advanced/extending-electron-forge/)
diff --git a/SUMMARY.md b/docs/SUMMARY.md
similarity index 88%
rename from SUMMARY.md
rename to docs/SUMMARY.md
index c3c9ed5..176d140 100644
--- a/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -6,15 +6,15 @@
## Configuration
-* [Overview](config/configuration.md)
+* [Overview](config/configuration.mdx)
* [Plugins](config/plugins/README.md)
- * [Webpack Plugin](config/plugins/webpack.md)
- * [Vite Plugin](config/plugins/vite.md)
+ * [Webpack Plugin](config/plugins/webpack.mdx)
+ * [Vite Plugin](config/plugins/vite.mdx)
* [Electronegativity Plugin](config/plugins/electronegativity.md)
* [Auto Unpack Native Modules Plugin](config/plugins/auto-unpack-natives.md)
* [Local Electron Plugin](config/plugins/local-electron.md)
- * [Fuses Plugin](config/plugins/fuses.md)
-* [Makers](config/makers/README.md)
+ * [Fuses Plugin](config/plugins/fuses.mdx)
+* [Makers](config/makers/README.mdx)
* [AppX](config/makers/appx.md)
* [deb](config/makers/deb.md)
* [DMG](config/makers/dmg.md)
@@ -55,9 +55,9 @@
* [Custom App Icons](guides/create-and-add-icons.md)
* [Framework Integration](guides/framework-integration/README.md)
* [Parcel](guides/framework-integration/parcel.md)
- * [React](guides/framework-integration/react.md)
- * [React with TypeScript](guides/framework-integration/react-with-typescript.md)
- * [Vue 3](guides/framework-integration/vue-3.md)
+ * [React](guides/framework-integration/react.mdx)
+ * [React with TypeScript](guides/framework-integration/react-with-typescript.mdx)
+ * [Vue 3](guides/framework-integration/vue-3.mdx)
* [Developing with WSL](guides/developing-with-wsl.md)
## Advanced
diff --git a/advanced/auto-update.md b/docs/advanced/auto-update.md
similarity index 100%
rename from advanced/auto-update.md
rename to docs/advanced/auto-update.md
diff --git a/advanced/debugging.md b/docs/advanced/debugging.md
similarity index 94%
rename from advanced/debugging.md
rename to docs/advanced/debugging.md
index 67fe12a..32259f9 100644
--- a/advanced/debugging.md
+++ b/docs/advanced/debugging.md
@@ -7,9 +7,9 @@ In Electron apps, the main and renderer processes have different debugging mecha
This guide goes over Forge-specific ways of debugging the main process through the command line or with a code editor.
-{% hint style="info" %}
+:::info
Each section in this guide assumes your `package.json` has a `"start": "electron-forge start"` script.
-{% endhint %}
+:::
For more general information on debugging Electron apps, see the [main Electron docs on Application Debugging](https://www.electronjs.org/docs/latest/tutorial/application-debugging#renderer-process).
@@ -23,16 +23,15 @@ npm run start -- --inspect-electron
Once your app is active, open [`chrome://inspect`](chrome://inspect) in any Chromium-based browser to attach a debugger to the main process of your app.
-{% hint style="info" %}
+:::info
To add a breakpoint at the first line of execution when debugging, you can use Forge's `--inspect-brk-electron` flag instead.
-{% endhint %}
+:::
## Debugging with VS Code
To debug the main process through VS Code, add the following [Node.js launch configuration](https://code.visualstudio.com/docs/nodejs/nodejs-debugging):
-{% code title=".vscode/launch.json" %}
-```json5
+```json title=".vscode/launch.json"
{
"configurations": [
{
@@ -54,7 +53,7 @@ To debug the main process through VS Code, add the following [Node.js launch con
]
}
```
-{% endcode %}
+
Once this configuration is added, launch the app via VS Code's Run and Debug view to start debugging.
diff --git a/advanced/extending-electron-forge/README.md b/docs/advanced/extending-electron-forge/README.md
similarity index 100%
rename from advanced/extending-electron-forge/README.md
rename to docs/advanced/extending-electron-forge/README.md
diff --git a/advanced/extending-electron-forge/writing-makers.md b/docs/advanced/extending-electron-forge/writing-makers.md
similarity index 98%
rename from advanced/extending-electron-forge/writing-makers.md
rename to docs/advanced/extending-electron-forge/writing-makers.md
index 2b6102f..544a09c 100644
--- a/advanced/extending-electron-forge/writing-makers.md
+++ b/docs/advanced/extending-electron-forge/writing-makers.md
@@ -18,7 +18,7 @@ This method must synchronously return a boolean indicating whether or not this m
If the issue is a missing dependency you should log out a **helpful** error message telling the developer exactly what is missing and if possible how to get it.
-```javascript
+```jsx
export default class MyMaker extends MakerBase {
isSupportedOnCurrentPlatform () {
return process.platform === 'linux' && this.isFakeRootInstalled();
@@ -36,7 +36,7 @@ The `config` for the maker will be available on `this.config`.
The options object is documented in [`MakerOptions`](https://js.electronforge.io/interfaces/_electron_forge_maker_base.MakerOptions.html).
-```javascript
+```jsx
export default class MyMaker extends MakerBase {
async make (opts) {
const pathToMagicInstaller = await makeMagicInstaller(opts.dir);
diff --git a/advanced/extending-electron-forge/writing-plugins.md b/docs/advanced/extending-electron-forge/writing-plugins.md
similarity index 94%
rename from advanced/extending-electron-forge/writing-plugins.md
rename to docs/advanced/extending-electron-forge/writing-plugins.md
index 640e4eb..82e803d 100644
--- a/advanced/extending-electron-forge/writing-plugins.md
+++ b/docs/advanced/extending-electron-forge/writing-plugins.md
@@ -6,9 +6,9 @@ An Electron Forge Plugin has to export a single class that extends our base plug
If implemented this method will be once during plugin initialization inside Forge, this method is called only once and shouldn't result in any side effects being executed. You must return an object in a similar format to `forgeConfig.hooks`. i.e. an object map between hook names and an array of hook functions.
-The possible hook names and the parameters passed to the hook function you return are documented over in the [Configuration](../../config/configuration.md) section of the docs.
+The possible hook names and the parameters passed to the hook function you return are documented over in the [Configuration](../../config/configuration.mdx) section of the docs.
-```javascript
+```jsx
export default class MyPlugin extends PluginBase {
getHooks () {
return {
@@ -28,11 +28,11 @@ If implemented, this method will be called every time the user runs `electron-fo
Please note that overriding the start logic here only works in **development** if you want to change how an app runs once packaged you will need to use a build hook to inject code into the packaged app.
-{% hint style="info" %}
+:::info
`StartOptions`is explained further [in the API docs](https://js.electronforge.io/interfaces/\_electron\_forge\_shared\_types.StartOptions.html).
-{% endhint %}
+:::
-```javascript
+```jsx
export default class MyPlugin extends Pluginbase {
async startLogic (opts) {
await this.compileMainProcess();
diff --git a/advanced/extending-electron-forge/writing-publishers.md b/docs/advanced/extending-electron-forge/writing-publishers.md
similarity index 99%
rename from advanced/extending-electron-forge/writing-publishers.md
rename to docs/advanced/extending-electron-forge/writing-publishers.md
index dd91326..d3a1025 100644
--- a/advanced/extending-electron-forge/writing-publishers.md
+++ b/docs/advanced/extending-electron-forge/writing-publishers.md
@@ -16,7 +16,7 @@ The `config` for the publisher will be available on `this.config`.
The options object is documented in [`PublisherOptions`](https://js.electronforge.io/interfaces/_electron_forge_publisher_base.PublisherOptions.html).
-```javascript
+```jsx
export default class MyPublisher extends PublisherBase {
async publish (opts) {
for (const result of opts.makeResults) {
diff --git a/advanced/extending-electron-forge/writing-templates.md b/docs/advanced/extending-electron-forge/writing-templates.md
similarity index 100%
rename from advanced/extending-electron-forge/writing-templates.md
rename to docs/advanced/extending-electron-forge/writing-templates.md
diff --git a/cli.md b/docs/cli.md
similarity index 95%
rename from cli.md
rename to docs/cli.md
index 6be5562..5ca3296 100644
--- a/cli.md
+++ b/docs/cli.md
@@ -6,13 +6,13 @@ description: How to use the command line interface (CLI) commands for Electron F
## Overview
-Forge's CLI is the main way to run Electron Forge commands. It consists of a thin wrapper for its core API. Configuration for these commands is done through your [Forge configuration](config/configuration.md) object.
+Forge's CLI is the main way to run Electron Forge commands. It consists of a thin wrapper for its core API. Configuration for these commands is done through your [Forge configuration](./config/configuration.mdx) object.
If you want to use the core API programmatically, see the [#programmatic-usage](cli.md#programmatic-usage "mention") section below.
-{% hint style="info" %}
+:::info
Forge's CLI uses comma-separated value strings to pass multiple arguments into a single flag. Depending on your terminal, these comma-separated values may need to be enclosed in quotation marks.
-{% endhint %}
+:::
## Installation
@@ -29,9 +29,9 @@ These commands help you get started with Forge. If you're just getting started w
### Init
-{% hint style="info" %}
+:::info
We recommend using the `create-electron-app` script (which uses this command) to get started rather than running Init directly.
-{% endhint %}
+:::
This command will initialize a new Forge-powered application in the given directory (defaults to `.`, the current directory).
@@ -70,9 +70,9 @@ npx electron-forge import
The Package, Make, and Publish commands are the three main steps of the Electron Forge build pipeline. Each step relies on the output of the previous one, so they are cascading by default (e.g. running `publish` will first run `package` then `make`.
-{% hint style="info" %}
+:::info
For more conceptual details, see the [build-lifecycle.md](core-concepts/build-lifecycle.md "mention") guide.
-{% endhint %}
+:::
### Package
@@ -148,11 +148,11 @@ All flags are optional.
#### Usage
-
# By default, the publish command corresponds to a publish npm script:
+
## Dev commands
@@ -162,7 +162,7 @@ This command will launch your app in dev mode with the `electron` binary in the
If you type `rs` (and hit enter) in the same terminal where you ran the start command, the running app will be terminated and restarted.
-Forge plugins can override this command to run custom development logic. For example, the [webpack.md](config/plugins/webpack.md "mention") runs a webpack-dev-server instance to provide live reloading and HMR.
+Forge plugins can override this command to run custom development logic. For example, the [webpack.md](config/plugins/webpack.mdx "mention") runs a webpack-dev-server instance to provide live reloading and HMR.
#### Options
@@ -189,7 +189,7 @@ npx electron-forge start --enable-logging
The Forge CLI should suit most use cases, but we do expose the `@electron-forge/core` package for programmatic command usage.
-```javascript
+```jsx
const { api } = require('@electron-forge/core');
const main = async () => {
diff --git a/config/configuration.md b/docs/config/configuration.mdx
similarity index 85%
rename from config/configuration.md
rename to docs/config/configuration.mdx
index 1691867..0d855f0 100644
--- a/config/configuration.md
+++ b/docs/config/configuration.mdx
@@ -2,6 +2,9 @@
description: How to configure Electron Forge
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# Overview
Electron Forge configuration is centralized in a single configuration object. You can specify this config in your package.json on the `config.forge` property. This property can have be in one of two forms:
@@ -11,10 +14,15 @@ Electron Forge configuration is centralized in a single configuration object. Yo
If you do not have `config.forge` set in your package.json file, Forge will attempt to find a `forge.config.js` file in your project root.
-{% tabs %}
-{% tab title="forge.config.js" %}
-{% code title="forge.config.js" %}
-```javascript
+
+
+
+```jsx title="forge.config.js"
module.exports = {
packagerConfig: {},
makers: [
@@ -24,12 +32,11 @@ module.exports = {
]
};
```
-{% endcode %}
-{% endtab %}
+
-{% tab title="package.json" %}
-{% code title="package.json" %}
-```json
+
+
+```json title="package.json"
{
"name": "my-app",
"version": "0.0.1",
@@ -45,19 +52,24 @@ module.exports = {
}
}
```
-{% endcode %}
-{% endtab %}
-{% endtabs %}
+
+
-{% hint style="info" %}
+:::info
We recommend using JavaScript for your config file since it enables conditional logic within your configuration.
-{% endhint %}
+:::
## Configuration options
-{% tabs %}
-{% tab title="forge.config.js" %}
-```javascript
+
+
+
+```jsx
module.exports = {
packagerConfig: { /* ... */ },
rebuildConfig: { /* ... */ },
@@ -68,10 +80,11 @@ module.exports = {
buildIdentifier: 'my-build'
};
```
-{% endtab %}
+
+
+
-{% tab title="package.json" %}
-```jsonc
+```json
// Only the relevant section of package.json is shown, for brevity.
{
"config": {
@@ -87,12 +100,12 @@ module.exports = {
}
}
```
-{% endtab %}
-{% endtabs %}
+
+
-{% hint style="success" %}
+:::info success
All properties are optional
-{% endhint %}
+:::
### Electron Packager config
@@ -100,9 +113,9 @@ The top level property `packagerConfig` on the configuration object maps directl
The options you can put in this object are documented in the [Electron Packager API docs](https://electron.github.io/packager/main/interfaces/Options.html).
-{% hint style="warning" %}
+:::warning
You can not override the `dir`, `arch`, `platform, out` or `electronVersion` options as they are set by Electron Forge internally.
-{% endhint %}
+:::
### Electron Rebuild config
@@ -110,9 +123,9 @@ The top level property `rebuildConfig` on the configuration object maps directly
The options you can put in this object are documented in the [Electron Rebuild API docs](https://github.com/electron/electron-rebuild#how-can-i-integrate-this-into-grunt--gulp--whatever).
-{% hint style="warning" %}
+:::warning
You can not override the `buildPath`, `arch`, or `electronVersion` options as they are set by Electron Forge internally
-{% endhint %}
+:::
### Makers
@@ -136,8 +149,7 @@ Check out the [hooks.md](hooks.md "mention") documentation for all possible hook
This property can be used to identify different build configurations. Normally, this property is set to the channel the build will release to, or some other unique identifier. For example, common values are `prod` and `beta`. This identifier can be used in conjunction with the `fromBuildIdentifier` function to generate release channel or environment specific configuration. For example:
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
const { utils: { fromBuildIdentifier } } = require('@electron-forge/core');
module.exports = {
@@ -147,6 +159,5 @@ module.exports = {
}
};
```
-{% endcode %}
In this example the `appBundleId` option passed to Electron Packager will be selected based on the `buildIdentifer` based on whether you are building for `prod` or `beta`. This allows you to make shared configs incredibly easily as only the values that change need to be wrapped with this function.
diff --git a/config/hooks.md b/docs/config/hooks.md
similarity index 96%
rename from config/hooks.md
rename to docs/config/hooks.md
index 688b528..60d32cf 100644
--- a/config/hooks.md
+++ b/docs/config/hooks.md
@@ -10,9 +10,9 @@ Each hook function comes with the Forge configuration object as a first paramete
Any writes to `stdout` and `stderr` from within a hook function will be printed in the console after the Forge build completes.
-{% hint style="info" %}
+:::info
To read more about the different stages in Forge's build process, please refer to the [build-lifecycle.md](../core-concepts/build-lifecycle.md "mention") documentation.
-{% endhint %}
+:::
## Simple hooks
@@ -43,8 +43,7 @@ For instance, you could use this hook to generate a license file containing the
You can use this hook to attach listeners to the spawned child process.
-{% code title="forge.config.js" fullWidth="false" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
hooks: {
postStart: async (forgeConfig, appProcess) => {
@@ -53,7 +52,7 @@ module.exports = {
}
};
```
-{% endcode %}
+
### `prePackage`
@@ -97,9 +96,9 @@ During Forge's **`package`** step, Electron Packager prunes non-production `node
The `afterPrune` hook runs after this prune step.
-{% hint style="info" %}
+:::info
`packageAfterPrune()` will have no effect if your `packagerOptions.prune` option is set to `false`.
-{% endhint %}
+:::
### `packageAfterExtract`
@@ -132,8 +131,7 @@ The `afterExtract` hook runs after this extract step.
For example:
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
hooks: {
postPackage: async (forgeConfig, options) => {
@@ -142,7 +140,7 @@ module.exports = {
}
};
```
-{% endcode %}
+
### `preMake`
@@ -182,8 +180,7 @@ The full package.json object is passed in as a parameter. If you want to modify
This is useful to set things like the package.json `version` field at runtime.
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
hooks: {
readPackageJson: async (forgeConfig, packageJson) => {
@@ -193,8 +190,8 @@ module.exports = {
}
};
```
-{% endcode %}
-{% hint style="warning" %}
+
+:::warning
**Note:** this hook will not change the name or version used by Electron Packager to customize your app metadata, as that is read prior to this hook being called (during Electron Packager's `afterCopy` hooks).
-{% endhint %}
+:::
diff --git a/config/makers/README.md b/docs/config/makers/README.mdx
similarity index 78%
rename from config/makers/README.md
rename to docs/config/makers/README.mdx
index c90db8b..61faabe 100644
--- a/config/makers/README.md
+++ b/docs/config/makers/README.mdx
@@ -4,15 +4,24 @@ description: >-
Forge.
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# Makers
Makers are Electron Forge's way of taking your packaged application and making platform specific distributables like DMG, EXE, or Flatpak files \(amongst others\).
Each maker has to be configured in the `makers` section of your forge configuration with which platforms to run for and the maker specific config. E.g.
-{% tabs %}
-{% tab title="package.json" %}
-```jsonc
+
+
+
+```json
// If your config is only in package.json:
// Only showing the relevant configuration for brevity
{
@@ -31,10 +40,11 @@ Each maker has to be configured in the `makers` section of your forge configurat
}
}
```
-{% endtab %}
+
+
+
-{% tab title="forge.config.js" %}
-```javascript
+```jsx
// If you have set config.forge to a JavaScript file path in package.json:
// Only showing the relevant configuration for brevity
module.exports = {
@@ -49,8 +59,8 @@ module.exports = {
]
};
```
-{% endtab %}
-{% endtabs %}
+
+
Please note that all makers have logical defaults for the `platforms` value so you normally don't need to specify that property.
diff --git a/config/makers/appx.md b/docs/config/makers/appx.md
similarity index 98%
rename from config/makers/appx.md
rename to docs/config/makers/appx.md
index 468de7b..df4b896 100644
--- a/config/makers/appx.md
+++ b/docs/config/makers/appx.md
@@ -12,7 +12,7 @@ Configuration options are documented in [`MakerAppXConfig`](https://js.electronf
### Usage
-```javascript
+```jsx
{
name: '@electron-forge/maker-appx',
config: {
diff --git a/config/makers/deb.md b/docs/config/makers/deb.md
similarity index 98%
rename from config/makers/deb.md
rename to docs/config/makers/deb.md
index 47bee8e..f54ab31 100644
--- a/config/makers/deb.md
+++ b/docs/config/makers/deb.md
@@ -12,7 +12,7 @@ Configuration options are documented in [`MakerDebConfig`](https://js.electronfo
### Usage
-```javascript
+```jsx
{
name: '@electron-forge/maker-deb',
config: {
diff --git a/config/makers/dmg.md b/docs/config/makers/dmg.md
similarity index 92%
rename from config/makers/dmg.md
rename to docs/config/makers/dmg.md
index ce714e8..3c8b607 100644
--- a/config/makers/dmg.md
+++ b/docs/config/makers/dmg.md
@@ -6,15 +6,15 @@ description: Generate a DMG with Electron Forge to distribute your Electron app
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.
-{% hint style="warning" %}
+:::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).
### Usage
-```javascript
+```jsx
{
name: '@electron-forge/maker-dmg',
config: {
diff --git a/config/makers/flatpak.md b/docs/config/makers/flatpak.md
similarity index 98%
rename from config/makers/flatpak.md
rename to docs/config/makers/flatpak.md
index 76f26b1..aff8c74 100644
--- a/config/makers/flatpak.md
+++ b/docs/config/makers/flatpak.md
@@ -12,7 +12,7 @@ Configuration options are documented in [`MakerFlatpakConfig`](https://js.electr
### Usage
-```javascript
+```jsx
{
name: '@electron-forge/maker-flatpak',
config: {
diff --git a/config/makers/pkg.md b/docs/config/makers/pkg.md
similarity index 97%
rename from config/makers/pkg.md
rename to docs/config/makers/pkg.md
index 825abdc..861352f 100644
--- a/config/makers/pkg.md
+++ b/docs/config/makers/pkg.md
@@ -10,7 +10,7 @@ Configuration options are documented in [`MakerPkgConfig`](https://js.electronfo
### Usage
-```javascript
+```jsx
{
name: '@electron-forge/maker-pkg',
config: {
diff --git a/config/makers/rpm.md b/docs/config/makers/rpm.md
similarity index 98%
rename from config/makers/rpm.md
rename to docs/config/makers/rpm.md
index abf5a44..e50efdb 100644
--- a/config/makers/rpm.md
+++ b/docs/config/makers/rpm.md
@@ -28,7 +28,7 @@ sudo apt-get install rpm
Configuration options are documented in [`MakerRpmConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_rpm.MakerRpmConfig.html).
-```javascript
+```jsx
{
name: '@electron-forge/maker-rpm',
config: {
diff --git a/config/makers/snapcraft.md b/docs/config/makers/snapcraft.md
similarity index 98%
rename from config/makers/snapcraft.md
rename to docs/config/makers/snapcraft.md
index 28b2340..0572c74 100644
--- a/config/makers/snapcraft.md
+++ b/docs/config/makers/snapcraft.md
@@ -12,7 +12,7 @@ Configuration options are documented in [`MakerSnapConfig`](https://js.electronf
## Usage
-```javascript
+```jsx
{
name: '@electron-forge/maker-snap',
config: {
diff --git a/config/makers/squirrel.windows.md b/docs/config/makers/squirrel.windows.md
similarity index 82%
rename from config/makers/squirrel.windows.md
rename to docs/config/makers/squirrel.windows.md
index db2132a..947f6e5 100644
--- a/config/makers/squirrel.windows.md
+++ b/docs/config/makers/squirrel.windows.md
@@ -6,7 +6,7 @@ description: Create a Windows installer for your Electron app using Electron For
The Squirrel.Windows target builds your application using the [Squirrel.Windows](https://github.com/Squirrel/Squirrel.Windows) framework. It generates three files:
-
File
Description
{appName} Setup.exe
The main executable installer for your application
{appName}-full.nupkg
The NuGet package file used for updates
RELEASES
Metadata file used to check if an update is available
+
File
Description
\{appName\} Setup.exe
The main executable installer for your application
\{appName\}-full.nupkg
The NuGet package file used for updates
RELEASES
Metadata file used to check if an update is available
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.
@@ -14,10 +14,9 @@ You can only build the Squirrel.Windows target on a Windows machine or on a Linu
## Usage
-Add this module to the [makers](./) section of your [Forge configuration](../configuration.md):
+Add this module to the [makers](./) section of your [Forge configuration](../configuration.mdx):
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
makers: [
{
@@ -30,7 +29,7 @@ module.exports = {
]
};
```
-{% endcode %}
+
## Configuration
@@ -46,8 +45,7 @@ Squirrel.Windows requires mandatory package metadata to satisfy the [`.nuspec`](
By default, the Squirrel.Windows maker fetches the `author` and `description` fields in the project's package.json file.
-{% code title="package.json" %}
-```jsonc
+```json title="package.json"
{
// ...
"author": "Alice and Bob",
@@ -55,14 +53,13 @@ By default, the Squirrel.Windows maker fetches the `author` and `description` fi
// ...
}
```
-{% endcode %}
+
#### In your Forge config
Alternatively, you can also override these values directly in your Squirrel.Windows maker config.
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
makers: [
{
@@ -75,11 +72,11 @@ module.exports = {
]
};
```
-{% endcode %}
-{% hint style="warning" %}
+
+:::warning
Note that the Forge config field is **"authors"** while the package.json field is called **"author".**
-{% endhint %}
+:::
## Handling startup events
@@ -87,11 +84,10 @@ When first running your app, updating it, and uninstalling it, Squirrel.Windows
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.
-{% code title="main.js" %}
-```javascript
+```jsx title="main.js"
const { app } = require('electron');
// run this as early in the main process as possible
if (require('electron-squirrel-startup')) app.quit();
```
-{% endcode %}
+
diff --git a/config/makers/wix-msi.md b/docs/config/makers/wix-msi.md
similarity index 98%
rename from config/makers/wix-msi.md
rename to docs/config/makers/wix-msi.md
index 02c7c5b..6a31025 100644
--- a/config/makers/wix-msi.md
+++ b/docs/config/makers/wix-msi.md
@@ -12,7 +12,7 @@ Configuration options are documented in [`MakerWixConfig`](https://js.electronfo
### Usage
-```javascript
+```jsx
{
name: '@electron-forge/maker-wix',
config: {
diff --git a/config/makers/zip.md b/docs/config/makers/zip.md
similarity index 95%
rename from config/makers/zip.md
rename to docs/config/makers/zip.md
index b260491..73f7c09 100644
--- a/config/makers/zip.md
+++ b/docs/config/makers/zip.md
@@ -8,7 +8,7 @@ The Zip target builds basic `.zip` files containing your packaged application.Th
### Usage
-```javascript
+```jsx
{
name: '@electron-forge/maker-zip'
}
diff --git a/config/plugins/README.md b/docs/config/plugins/README.md
similarity index 100%
rename from config/plugins/README.md
rename to docs/config/plugins/README.md
diff --git a/config/plugins/auto-unpack-natives.md b/docs/config/plugins/auto-unpack-natives.md
similarity index 75%
rename from config/plugins/auto-unpack-natives.md
rename to docs/config/plugins/auto-unpack-natives.md
index fcd657d..01b712b 100644
--- a/config/plugins/auto-unpack-natives.md
+++ b/docs/config/plugins/auto-unpack-natives.md
@@ -6,7 +6,7 @@ description: >-
# Auto Unpack Native Modules Plugin
-This plugin will automatically add all native Node modules in your `node_modules` folder to the [`asar.unpack`](https://electron.github.io/electron-packager/main/interfaces/electronpackager.options.html#asar) config option in your [`packagerConfig`](../configuration.md#electron-packager-config). If your app uses native Node modules, you should probably use this to reduce loading times and disk consumption on your users' machines.
+This plugin will automatically add all native Node modules in your `node_modules` folder to the [`asar.unpack`](https://electron.github.io/electron-packager/main/interfaces/electronpackager.options.html#asar) config option in your [`packagerConfig`](../configuration.mdx#electron-packager-config). If your app uses native Node modules, you should probably use this to reduce loading times and disk consumption on your users' machines.
## Installation
@@ -16,14 +16,13 @@ npm install --save-dev @electron-forge/plugin-auto-unpack-natives
## Usage
-You must add this plugin to your [`plugins`](../configuration.md#plugins) array in your Forge configuration. There are currently no configuration options available for this plugin.
+You must add this plugin to your [`plugins`](../configuration.mdx#plugins) array in your Forge configuration. There are currently no configuration options available for this plugin.
-{% hint style="info" %}
+:::info
Asar archives are disabled by default with Electron Packager. Make sure you set your `packagerConfig.asar` value accordingly. This option also supports advanced configuration if you pass it an object. See the [API documentation for this option](https://js.electronforge.io/modules/\_electron\_forge\_shared\_types.InternalOptions.html#CreateOptions) for more information.
-{% endhint %}
+:::
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
packagerConfig: {
asar: true // or an object containing your asar options
@@ -36,4 +35,4 @@ module.exports = {
]
};
```
-{% endcode %}
+
diff --git a/config/plugins/electronegativity.md b/docs/config/plugins/electronegativity.md
similarity index 69%
rename from config/plugins/electronegativity.md
rename to docs/config/plugins/electronegativity.md
index 4eef26d..f690b46 100644
--- a/config/plugins/electronegativity.md
+++ b/docs/config/plugins/electronegativity.md
@@ -16,12 +16,11 @@ npm install --save-dev @electron-forge/plugin-electronegativity
## Usage
-Add this plugin to the [`plugins`](../configuration.md#plugins) array in your Forge configuration. All [programmatic options for Electronegativity](https://github.com/doyensec/electronegativity#programmatically), except for `input` and `electronVersion`.
+Add this plugin to the [`plugins`](../configuration.mdx#plugins) array in your Forge configuration. All [programmatic options for Electronegativity](https://github.com/doyensec/electronegativity#programmatically), except for `input` and `electronVersion`.
### Example
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
plugins: [
@@ -35,4 +34,4 @@ module.exports = {
// ...
};
```
-{% endcode %}
+
diff --git a/config/plugins/fuses.md b/docs/config/plugins/fuses.mdx
similarity index 88%
rename from config/plugins/fuses.md
rename to docs/config/plugins/fuses.mdx
index 4c23c39..9fe65bb 100644
--- a/config/plugins/fuses.md
+++ b/docs/config/plugins/fuses.mdx
@@ -2,6 +2,9 @@
description: Toggle Electron functionality at package-time with Electron Fuses.
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# Fuses Plugin
> Added in version 6.1.0
@@ -16,9 +19,9 @@ For an updated list of the features that can be enabled/disabled using Fuses, pl
## Installation
-{% hint style="info" %}
+:::info
This plugin has a peer dependency on `@electron/fuses`, so don't forget to install it too!
-{% endhint %}
+:::
```shell
npm install --save-dev @electron-forge/plugin-fuses @electron/fuses
@@ -28,8 +31,13 @@ npm install --save-dev @electron-forge/plugin-fuses @electron/fuses
You can use the `FusesPlugin` constructor just like the `flipFuses` function from `@electron/fuses`, except that the plugin already takes care of the Electron path for you, so you only need to provide the configuration object.
-{% tabs %}
-{% tab title="forge.config.js" %}
+
+
+
```js
const { FusesPlugin } = require('@electron-forge/plugin-fuses');
const { FuseV1Options, FuseVersion } = require('@electron/fuses');
@@ -48,14 +56,18 @@ const forgeConfig = {
module.exports = forgeConfig;
```
-
-{% endtab %}
-{% endtabs %}
+
+
The example above assumes you're using `@electron/fuses` v1.x, which is the latest major version as of the time of writing; however, this plugin should work with any version of `@electron/fuses`. For instance, if `@electron/fuses` v2.x is released and you want to use some new fuse that comes with it, you'll just need to upgrade your `@electron/fuses` package to v2.x and update your Forge configuration:
-{% tabs %}
-{% tab title="forge.config.js" %}
+
+
+
```js
const { FusesPlugin } = require('@electron-forge/plugin-fuses');
const { FuseV2Options, FuseVersion } = require('@electron/fuses');
@@ -74,7 +86,5 @@ const forgeConfig = {
module.exports = forgeConfig;
```
-
-{% endtab %}
-{% endtabs %}
-
+
+
\ No newline at end of file
diff --git a/config/plugins/local-electron.md b/docs/config/plugins/local-electron.md
similarity index 91%
rename from config/plugins/local-electron.md
rename to docs/config/plugins/local-electron.md
index ee6ae00..19279d5 100644
--- a/config/plugins/local-electron.md
+++ b/docs/config/plugins/local-electron.md
@@ -4,9 +4,9 @@ description: Integrate a local build of Electron into your Forge app.
# Local Electron Plugin
-{% hint style="info" %}
+:::info
This plugin should only be used by people who are building Electron locally themselves. If you want to use a fork of Electron, check out the [environment variables](https://github.com/electron/get#usage) you can use to configure `@electron/get`.
-{% endhint %}
+:::
This plugin allows you to both run and build your app using a **local** build of Electron. This can be incredibly useful if you want to test a feature or a bug fix in your app before making a PR up to the Electron repository.
@@ -24,8 +24,7 @@ Once you have a working build of Electron, point the plugin's `electronPath` con
All possible configuration options are documented in [`LocalElectronPluginConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_plugin\_local\_electron.LocalElectronPluginConfig.html).
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
{
plugins: [
{
@@ -37,8 +36,8 @@ All possible configuration options are documented in [`LocalElectronPluginConfig
]
}
```
-{% endcode %}
-{% hint style="info" %}
+
+:::info
Please note that the plugin only accepts **absolute paths**. You should use Node's [`path.resolve()`](https://nodejs.org/api/path.html#pathresolvepaths) to make things deterministic.
-{% endhint %}
+:::
diff --git a/config/plugins/vite.md b/docs/config/plugins/vite.mdx
similarity index 63%
rename from config/plugins/vite.md
rename to docs/config/plugins/vite.mdx
index 04efce3..05d22b8 100644
--- a/config/plugins/vite.md
+++ b/docs/config/plugins/vite.mdx
@@ -2,6 +2,9 @@
description: Transform and bundle code for your Electron Forge app with Vite.
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# Vite Plugin
This plugin makes it easy to set up standard Vite tooling to compile both your main process code and your renderer process code.
@@ -18,15 +21,21 @@ npm install --save-dev @electron-forge/plugin-vite
You must provide two Vite configuration files: one for the main process in `vite.main.config.js`, and one for the renderer process in `vite.renderer.config.js`.
-For example, this is the [configuration](../configuration.md) taken from Forge's [Vite template](../../templates/vite.md):
+For example, this is the [configuration](../configuration.mdx) taken from Forge's [Vite template](../../templates/vite.md):
+
+
+
-{% tabs %}
-{% tab title="forge.config.js" %}
-```javascript
+```jsx
module.exports = {
plugins: [
{
- name: '@electron-forge/plugin-vite',
+ name: "@electron-forge/plugin-vite",
config: {
// `build` can specify multiple entry builds, which can be
// Main process, Preload scripts, Worker process, etc.
@@ -34,29 +43,31 @@ module.exports = {
{
// `entry` is an alias for `build.lib.entry`
// in the corresponding file of `config`.
- entry: 'src/main.js',
- config: 'vite.main.config.mjs'
+ entry: "src/main.js",
+ config: "vite.main.config.mjs",
},
{
- entry: 'src/preload.js',
- config: 'vite.preload.config.mjs'
- }
+ entry: "src/preload.js",
+ config: "vite.preload.config.mjs",
+ },
],
renderer: [
{
- name: 'main_window',
- config: 'vite.renderer.config.mjs'
- }
- ]
- }
- }
- ]
+ name: "main_window",
+ config: "vite.renderer.config.mjs",
+ },
+ ],
+ },
+ },
+ ],
};
```
-{% endtab %}
-{% tab title="package.json" %}
-```jsonc
+
+
+
+
+```json
{
// ...
"config": {
@@ -68,19 +79,19 @@ module.exports = {
"build": [
{
"entry": "src/main.js",
- "config": "vite.main.config.mjs",
+ "config": "vite.main.config.mjs"
},
{
"entry": "src/preload.js",
- "config": "vite.preload.config.mjs",
- },
+ "config": "vite.preload.config.mjs"
+ }
],
"renderer": [
{
"name": "main_window",
- "config": "vite.renderer.config.mjs",
- }]
- }
+ "config": "vite.renderer.config.mjs"
+ }
+ ]
}
}
]
@@ -89,8 +100,9 @@ module.exports = {
// ...
}
```
-{% endtab %}
-{% endtabs %}
+
+
+
Config options will largely follow the same standards as non-Electron Vite projects. You can reference [Vite's documentation here](https://vitejs.dev/config/) for more examples of how to configure each of your entry point's config files.
@@ -100,15 +112,13 @@ Vite's build config generates a separate entry for the main process and preload
Your `main` entry in your `package.json` file needs to point at `".vite/build/main"`, like so:
-{% code title="package.json" %}
-```jsonc
+```json title="package.json"
{
"name": "my-vite-app",
- "main": ".vite/build/main.js",
+ "main": ".vite/build/main.js"
// ...
}
```
-{% endcode %}
If using the Vite template, this should be automatically set up for you.
@@ -118,48 +128,46 @@ If using the Vite template, this should be automatically set up for you.
If you used the [Vite](../../templates/vite.md) template to create your application, native modules will mostly work out of the box. However, to avoid possible build issues, we recommend instructing Vite to load them as external packages:
-{% code title="vite.main.config.js" %}
-```javascript
-import { defineConfig } from 'vite';
+```jsx title="vite.main.config.js"
+import { defineConfig } from "vite";
export default defineConfig({
build: {
rollupOptions: {
- external: [
- 'serialport',
- 'sqlite3'
- ]
- }
- }
+ external: ["serialport", "sqlite3"],
+ },
+ },
});
```
-{% endcode %}
### Hot Module Replacement (HMR)
In order to use Vite's [Hot Module Replacement (HMR)](https://vitejs.dev/guide/features.html#hot-module-replacement), all `loadURL` paths need to reference the global variables that the Vite plugin will define for you:
-* The dev server will be suffixed with `_DEV_SERVER_URL`
-* The static file path will be suffixed with `_VITE_NAME`
+- The dev server will be suffixed with `_DEV_SERVER_URL`
+- The static file path will be suffixed with `_VITE_NAME`
In the case of the `main_window`, the global variables will be named `MAIN_WINDOW_VITE_DEV_SERVER_URL` and `MAIN_WINDOW_VITE_NAME`. An example of how to use them is given below:
-{% code title="main.js" %}
-```javascript
-const mainWindow = new BrowserWindow({ /* ... */ });
+```jsx title="main.js"
+const mainWindow = new BrowserWindow({
+ /* ... */
+});
if (MAIN_WINDOW_VITE_DEV_SERVER_URL) {
mainWindow.loadURL(MAIN_WINDOW_VITE_DEV_SERVER_URL);
} else {
- mainWindow.loadFile(path.join(__dirname, `../renderer/${MAIN_WINDOW_VITE_NAME}/index.html`));
-};
+ mainWindow.loadFile(
+ path.join(__dirname, `../renderer/${MAIN_WINDOW_VITE_NAME}/index.html`)
+ );
+}
```
-{% endcode %}
-{% hint style="info" %}
+:::info
If using TypeScript, the variables can be defined as such:
-
-{% endhint %}
+```tsx
+declare const MAIN_WINDOW_VITE_DEV_SERVER_URL: string;
+declare const MAIN_WINDOW_VITE_NAME: string;
+```
+:::
diff --git a/config/plugins/webpack.md b/docs/config/plugins/webpack.mdx
similarity index 91%
rename from config/plugins/webpack.md
rename to docs/config/plugins/webpack.mdx
index 1c24527..54b0f29 100644
--- a/config/plugins/webpack.md
+++ b/docs/config/plugins/webpack.mdx
@@ -2,6 +2,9 @@
description: Transform and bundle code for your Electron Forge app with webpack.
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# Webpack Plugin
This plugin makes it easy to set up standard [webpack](https://webpack.js.org/) tooling to compile both your main process code and your renderer process code, with built-in support for [Hot Module Replacement (HMR)](https://webpack.js.org/concepts/hot-module-replacement/) in the renderer process and support for multiple renderers.
@@ -18,11 +21,17 @@ npm install --save-dev @electron-forge/plugin-webpack
You must provide two webpack configuration files: one for the main process in `mainConfig`, and one for the renderer process in `renderer.config`. The complete config options are available in the API docs under [`WebpackPluginConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_plugin\_webpack.WebpackPluginConfig.html).
-For example, this is the [configuration](../configuration.md) taken from Forge's [webpack template](../../templates/webpack-template.md):
+For example, this is the [configuration](../configuration.mdx) taken from Forge's [webpack template](../../templates/webpack-template.md):
+
+
+
-{% tabs %}
-{% tab title="forge.config.js" %}
-```javascript
+```jsx
module.exports = {
// ...
plugins: [
@@ -47,10 +56,11 @@ module.exports = {
// ...
};
```
-{% endtab %}
+
-{% tab title="package.json" %}
-```jsonc
+
+
+```json
{
// ...
"config": {
@@ -79,8 +89,8 @@ module.exports = {
// ...
}
```
-{% endtab %}
-{% endtabs %}
+
+
### Project files
@@ -92,15 +102,14 @@ You need to do two things in your project files in order to make this plugin wor
First, your `main` entry in your `package.json` file needs to point at `"./.webpack/main"` like so:
-{% code title="package.json" %}
-```jsonc
+```json title="package.json"
{
"name": "my-app",
"main": "./.webpack/main",
// ...
}
```
-{% endcode %}
+
#### Main process code
@@ -113,8 +122,7 @@ Each entry point has two globals defined based on the name assigned to your entr
In the case of the `main_window` entry point in the earlier example, the global variables will be named `MAIN_WINDOW_WEBPACK_ENTRY` and `MAIN_WINDOW_PRELOAD_WEBPACK_ENTRY`. An example of how to use them is given below:
-{% code title="main.js" %}
-```javascript
+```jsx title="main.js"
const mainWindow = new BrowserWindow({
webPreferences: {
preload: MAIN_WINDOW_PRELOAD_WEBPACK_ENTRY
@@ -123,55 +131,59 @@ const mainWindow = new BrowserWindow({
mainWindow.loadURL(MAIN_WINDOW_WEBPACK_ENTRY);
```
-{% endcode %}
+
These variables are only defined in the main process. If you need to use one of these paths in a renderer (e.g. to pass a preload script to a `` tag), you can pass the magic variable value with a synchronous IPC round trip.
-{% tabs %}
-{% tab title="Main Process" %}
-{% code title="main.js" %}
-```javascript
+
+
+
+```jsx title="main.js"
// make sure this listener is set before your renderer.js code is called
ipcMain.on('get-preload-path', (e) => {
e.returnValue = WINDOW_PRELOAD_WEBPACK_ENTRY;
});
```
-{% endcode %}
-{% endtab %}
-{% tab title="Preload Script" %}
-{% code title="preload.js" %}
-```javascript
+
+
+
+
+```jsx title="preload.js"
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('electron', {
getPreloadPath: () => ipcRenderer.sendSync('get-preload-path')
});
```
-{% endcode %}
-{% endtab %}
-{% tab title="Renderer Process" %}
-{% code title="renderer.js" %}
-```javascript
+
+
+
+
+```jsx title="renderer.js"
const preloadPath = window.electron.getPreloadPath();
```
-{% endcode %}
-{% endtab %}
-{% endtabs %}
-{% hint style="info" %}
+
+
+
+:::info
**Usage with TypeScript**
If you're using the webpack plugin with TypeScript, you will need to manually declare these magic variables to avoid compiler errors.
-{% code title="main.js (Main Process)" %}
-```typescript
+```tsx title="main.js (Main Process)"
declare const MAIN_WINDOW_WEBPACK_ENTRY: string;
declare const MAIN_WINDOW_PRELOAD_WEBPACK_ENTRY: string;
```
-{% endcode %}
-{% endhint %}
+:::
## Advanced configuration
@@ -183,8 +195,7 @@ Forge's webpack plugin uses [`webpack-dev-server`](https://webpack.js.org/config
In development mode, you can change most `webpack-dev-server` options by setting `devServer` in your Forge Webpack plugin configuration.
-{% code title="Plugin configuration" %}
-```javascript
+```jsx title="Plugin configuration"
{
name: '@electron-forge/plugin-webpack',
config: {
@@ -196,13 +207,13 @@ In development mode, you can change most `webpack-dev-server` options by setting
}
}
```
-{% endcode %}
+
#### devContentSecurityPolicy
In development mode, you can set a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) by setting `devContentSecurityPolicy` in your Forge Webpack plugin configuration.
-```javascript
+```jsx
{
name: '@electron-forge/plugin-webpack',
config: {
@@ -217,9 +228,9 @@ In development mode, you can set a [Content Security Policy (CSP)](https://devel
}
```
-{% hint style="info" %}
+:::info
If you wish to use **source maps** in development, you'll need to set `'unsafe-eval'` for the [`script-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src) directive. Using `'unsafe-eval'` will cause Electron itself to trigger a warning in the DevTools console about having that value enabled, which is usually fine so long as you **do not set that value in production**.
-{% endhint %}
+:::
### Native Node modules
@@ -232,12 +243,11 @@ If you are setting up the plugin manually, you can make native modules work by a
npm install --save-dev node-loader @vercel/webpack-asset-relocator-loader@1.7.3
```
-{% hint style="warning" %}
+:::warning
Electron Forge monkeypatches the asset relocator loader in order for it to work with Electron properly, so the version has been pinned to ensure compatibility. If you upgrade that version, you do so at your own risk.
-{% endhint %}
+:::
-{% code title="webpack.main.config.js" %}
-```javascript
+```jsx title="webpack.main.config.js"
module.exports = {
module: {
rules: [
@@ -262,7 +272,7 @@ module.exports = {
}
};
```
-{% endcode %}
+
If the asset relocator loader does not work for your native module, you may want to consider using webpack's [externals configuration](https://webpack.js.org/configuration/externals/).
@@ -272,8 +282,7 @@ If the asset relocator loader does not work for your native module, you may want
In Electron, you can enable Node.js in the renderer process with [`BrowserWindow` constructor options](https://www.electronjs.org/docs/latest/api/browser-window). Renderers with the following options enabled will have a browser-like web environment with access to Node.js [`require`](https://nodejs.org/api/modules.html#requireid) and all of its core APIs:
-{% code title="main.js (Main Process)" %}
-```javascript
+```jsx title="main.js (Main Process)"
const win = new BrowserWindow({
webPreferences: {
contextIsolation: false,
@@ -281,7 +290,7 @@ const win = new BrowserWindow({
}
});
```
-{% endcode %}
+
This creates a unique environment that requires additional webpack configuration.
@@ -296,8 +305,7 @@ This option is **false** by default\*\*.\*\* You can set this option for all ren
In the below configuration example, webpack will compile to the `electron-renderer` target for all entry points except for `media_player`, which will compile to the `web` target.
-{% code title="Plugin configuration" %}
-```javascript
+```jsx title="Plugin configuration"
{
name: '@electron-forge/plugin-webpack',
config: {
@@ -322,11 +330,11 @@ In the below configuration example, webpack will compile to the `electron-render
}
}
```
-{% endcode %}
-{% hint style="warning" %}
+
+:::warning
It is important that you enable `nodeIntegration` in **both** in the main process code and the webpack plugin configuration. This option duplication is necessary because webpack targets are fixed upon compilation, but BrowserWindow's web preferences are determined on run time.
-{% endhint %}
+:::
## Hot module replacement
@@ -342,7 +350,7 @@ When using Webpack 5 caching, asset permissions need to be maintained through th
To insure these cases work out, make sure to run `initAssetCache` in the build, with the `options.outputAssetBase` argument:
-```javascript
+```jsx
const relocateLoader = require('@vercel/webpack-asset-relocator-loader');
webpack({
// ...
@@ -364,7 +372,7 @@ If you're using React components, you may want to have HMR automatically pick up
Here's a usage example in TypeScript with `App` being the topmost component in a React component tree:
-```typescript
+```tsx
import { hot } from "react-hot-loader";
const App: FunctionComponent = () => (
diff --git a/config/publishers/README.md b/docs/config/publishers/README.md
similarity index 92%
rename from config/publishers/README.md
rename to docs/config/publishers/README.md
index 14a9de9..25ca250 100644
--- a/config/publishers/README.md
+++ b/docs/config/publishers/README.md
@@ -4,8 +4,7 @@ Publishers are Electron Forge's way of taking the artifacts generated by the [`m
Each publisher has to be configured in the `publishers` section of your Forge configuration with which platforms to run for and the publisher specific config. For example:
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
publishers: [
{
@@ -19,7 +18,7 @@ module.exports = {
]
};
```
-{% endcode %}
+
Please note that all publishers default to publishing all platforms, so you only need to specify the `platforms` key if you don't want that default.
diff --git a/config/publishers/bitbucket.md b/docs/config/publishers/bitbucket.md
similarity index 85%
rename from config/publishers/bitbucket.md
rename to docs/config/publishers/bitbucket.md
index 29fa5d5..d96b25d 100644
--- a/config/publishers/bitbucket.md
+++ b/docs/config/publishers/bitbucket.md
@@ -6,16 +6,15 @@ description: >-
# Bitbucket
-{% hint style="warning" %}
+:::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).
## Usage
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
publishers: [
@@ -35,21 +34,20 @@ module.exports = {
]
};
```
-{% endcode %}
+
you can (and should) use environment variables for the authentication
-{% code title="env.sh" %}
-```bash
+```bash title="env.sh"
BITBUCKET_USERNAME="myusername"
BITBUCKET_APP_PASSWORD="mysecretapppassword"
```
-{% endcode %}
+
```bash
$ source env.sh
```
-{% hint style="info" %}
+:::info
Your artifacts can be found under the `Downloads` tab of your Bitbucket repository.
-{% endhint %}
+:::
diff --git a/config/publishers/electron-release-server.md b/docs/config/publishers/electron-release-server.md
similarity index 92%
rename from config/publishers/electron-release-server.md
rename to docs/config/publishers/electron-release-server.md
index 71a559d..15103d8 100644
--- a/config/publishers/electron-release-server.md
+++ b/docs/config/publishers/electron-release-server.md
@@ -8,8 +8,7 @@ Configuration options are documented in [`PublisherERSConfig`](https://js.electr
### Usage
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
publishers: [
@@ -24,4 +23,4 @@ module.exports = {
]
};
```
-{% endcode %}
+
diff --git a/config/publishers/gcs.md b/docs/config/publishers/gcs.md
similarity index 92%
rename from config/publishers/gcs.md
rename to docs/config/publishers/gcs.md
index 3ac679b..76326cd 100644
--- a/config/publishers/gcs.md
+++ b/docs/config/publishers/gcs.md
@@ -4,9 +4,9 @@ description: Publishing your Electron app artifacts to a Google Cloud Storage bu
# Google Cloud Storage
-{% hint style="info" %}
+:::info
This Publisher was added in Electron Forge **v7.1.0**.
-{% endhint %}
+:::
The Google Cloud Storage target publishes all your artifacts to a [Google Cloud Storage bucket](https://cloud.google.com/storage/docs).
@@ -20,8 +20,7 @@ We recommend following [Google's authentication documentation for client librari
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
+```jsx title="forge.config.js"
module.exports = {
// ...
publishers: [
@@ -40,7 +39,7 @@ module.exports = {
]
};
```
-{% endcode %}
+
When executed, the Publisher will publish to your GCS bucket under the following key:
@@ -50,6 +49,6 @@ ${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" %}
+:::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 %}
+:::
diff --git a/config/publishers/github.md b/docs/config/publishers/github.md
similarity index 90%
rename from config/publishers/github.md
rename to docs/config/publishers/github.md
index 7d2bbe4..6e40bf1 100644
--- a/config/publishers/github.md
+++ b/docs/config/publishers/github.md
@@ -4,14 +4,13 @@ The GitHub target publishes all your artifacts to GitHub releases, this allows y
Configuration options are documented in [`PublisherGitHubConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_github.PublisherGitHubConfig.html)
-{% hint style="info" %}
+:::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
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
publishers: [
@@ -28,17 +27,16 @@ module.exports = {
]
};
```
-{% endcode %}
+
### 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.
-{% code title="main.js" %}
-```javascript
+```jsx title="main.js"
const { updateElectronApp } = require('update-electron-app');
updateElectronApp(); // additional configuration options available
```
-{% endcode %}
+
If your GitHub release is in a private repository, you should check our [Auto Update](../../advanced/auto-update.md) guide for alternative solutions.
diff --git a/config/publishers/nucleus.md b/docs/config/publishers/nucleus.md
similarity index 88%
rename from config/publishers/nucleus.md
rename to docs/config/publishers/nucleus.md
index 09ae4a8..b169bfb 100644
--- a/config/publishers/nucleus.md
+++ b/docs/config/publishers/nucleus.md
@@ -4,14 +4,13 @@ The Nucleus target publishes all your artifacts to an instance of Nucleus Update
Configuration options are documented in [`PublisherNucleusConfig`](https://js.electronforge.io/interfaces/_electron_forge_publisher_nucleus.PublisherNucleusConfig.html)
-{% hint style="warning" %}
+:::warning
We recommend you set the `token` option using an environment variable, don't hard code it into your config
-{% endhint %}
+:::
## Usage
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
publishers: [
@@ -27,4 +26,4 @@ module.exports = {
]
};
```
-{% endcode %}
+
diff --git a/config/publishers/s3.md b/docs/config/publishers/s3.md
similarity index 92%
rename from config/publishers/s3.md
rename to docs/config/publishers/s3.md
index e89c070..77f9692 100644
--- a/config/publishers/s3.md
+++ b/docs/config/publishers/s3.md
@@ -14,8 +14,7 @@ It is recommended to follow the [Amazon AWS guide](https://docs.aws.amazon.com/s
Configuration options are documented in [`PublisherS3Config`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_s3.PublisherS3Config.html).
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
publishers: [
@@ -29,7 +28,7 @@ module.exports = {
]
};
```
-{% endcode %}
+
### Key management
@@ -40,13 +39,12 @@ By default, the S3 publisher will upload its objects to the `{prefix}/{platform}
* `{arch}` is the target architecture for the artifact you are publishing.
* `{name}` is the file name of the artifact you are publishing.
-{% hint style="warning" %}
+:::warning
If you run the Publish command multiple times on the same platform for the same version (e.g. simultaneously publishing `ia32` and `x64` Windows artifacts), your uploads can get overwritten in the S3 bucket.
To avoid this problem, you can use the `keyResolver` option to generate the S3 key programmatically.
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
{
name: '@electron-forge/publisher-s3',
config: {
@@ -58,8 +56,8 @@ To avoid this problem, you can use the `keyResolver` option to generate the S3 k
}
}
```
-{% endcode %}
-{% endhint %}
+
+:::
### Auto updating from S3
@@ -67,8 +65,7 @@ You can configure Electron's built-in [`autoUpdater`](https://www.electronjs.org
First, you must configure `@electron-forge/publisher-s3` to publish your files into an auto-updater compatible layout and use `@electron-forge/maker-zip` + `@electron-forge/maker-squirrel` to build your application.
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
makers: [
@@ -101,12 +98,11 @@ module.exports = {
]
};
```
-{% endcode %}
+
With Forge configured correctly, the second step is to configure the `autoUpdater` module inside your app's main process. The simplest form is shown below but you might want to hook additional events to show UI to your user or ask them if they want to update your app right now.
-{% code title="main.js" %}
-```javascript
+```jsx title="main.js"
const { updateElectronApp, UpdateSourceType } = require('update-electron-app');
updateElectronApp({
@@ -116,4 +112,4 @@ updateElectronApp({
}
});
```
-{% endcode %}
+
diff --git a/config/publishers/snapcraft.md b/docs/config/publishers/snapcraft.md
similarity index 91%
rename from config/publishers/snapcraft.md
rename to docs/config/publishers/snapcraft.md
index 6ceebef..ea2ab4d 100644
--- a/config/publishers/snapcraft.md
+++ b/docs/config/publishers/snapcraft.md
@@ -8,8 +8,7 @@ Configuration options are documented in [`PublisherSnapConfig`](https://js.elect
### Usage
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
publishers: [
@@ -22,4 +21,4 @@ module.exports = {
]
};
```
-{% endcode %}
+
diff --git a/core-concepts/build-lifecycle.md b/docs/core-concepts/build-lifecycle.md
similarity index 79%
rename from core-concepts/build-lifecycle.md
rename to docs/core-concepts/build-lifecycle.md
index 9acaf04..7c3204c 100644
--- a/core-concepts/build-lifecycle.md
+++ b/docs/core-concepts/build-lifecycle.md
@@ -6,21 +6,22 @@ description: How Forge takes your app code from development to distribution.
Once your app is ready to be released, Electron Forge can handle the rest to make sure it gets into your users' hands. The complete build flow for Electron Forge can be broken down into three smaller steps:
-
Forge's build flow
+
+Forge's build flow
Each one of these steps is a separate command exposed through Forge's `electron-forge` command line interface, and is usually mapped to a script in your package.json file.
-{% hint style="info" %}
+:::info
**Cascading build steps**
Running each of these tasks will also run the previous ones in the sequence (i.e. running the `electron-forge publish` script will first run `package` and `make` as prerequisite steps).
-{% endhint %}
+:::
## Step 1: Package
-{% hint style="info" %}
+:::info
For command usage, see the [#package](../cli.md#package "mention") CLI command documentation.
-{% endhint %}
+:::
In the Package step, Forge uses [Electron Packager](https://github.com/electron/electron-packager) to package your app. This means creating an executable bundle for a target operating system (e.g. `.app` on macOS or `.exe` on Windows).
@@ -32,23 +33,23 @@ This step also performs a few supporting tasks:
By default, running the Package step will only create a packaged application for your machine's platform and architecture.
-{% hint style="info" %}
+:::info
**On bundling app code**
Note that Forge does _not_ perform any bundling of your app code for production in the Package step without additional configuration.
If you need to perform any custom JavaScript build tasks (e.g. module bundling with Parcel or webpack) for either renderer or main process code, see the [#using-lifecycle-hooks](build-lifecycle.md#using-lifecycle-hooks "mention") section below.
-{% endhint %}
+:::
-{% hint style="success" %}
+:::info success
After the Package step, your packaged application will be available in the `/out/` directory.
-{% endhint %}
+:::
## Step 2: Make
-{% hint style="info" %}
+:::info
For command usage, see the [#make](../cli.md#make "mention") CLI command documentation.
-{% endhint %}
+:::
Forge's **Make** step takes the bundled executable output from the previous Package step and creates "**distributables**" from it. Distributables refer to any output format that you want to distribute to users, whether it be an OS-specific installer (e.g. `.dmg` or `.msi`) or a simple compressed archive (e.g. `.zip`) of the bundle.
@@ -56,23 +57,23 @@ You can choose which distributables you want to build by adding [makers](../conf
By default, running the Make step will only run Makers targeting your machine's platform and architecture.
-{% hint style="success" %}
+:::info success
After the Make step, distributable archives or installers are generated for your packaged app in the `/out/make/` folder of your project.
-{% endhint %}
+:::
## Step 3: Publish
-{% hint style="info" %}
+:::info
For command usage, see the [#publish](../cli.md#publish "mention") CLI command documentation.
-{% endhint %}
+:::
Forge's **Publish** step takes the distributable build artifacts from the Make step and uploads for distribution to your app's end users (e.g. to GitHub Releases or AWS S3 static storage). Publishing is an optional step in the Electron Forge pipeline, since the artifacts from the Make step are already in their final format.
You can choose which platforms you want to target by adding [publishers](../config/publishers/ "mention") to your Forge config.
-{% hint style="success" %}
+:::info success
After the Publish step, your app distributables will be available to download by users.
-{% endhint %}
+:::
## Using lifecycle hooks
@@ -80,11 +81,11 @@ Your Electron application might have custom build needs that aren't handled with
These hooks can be used to implement custom logic that your application needs. For instance, you can perform actions between the Package and Make steps with the `premake` hook.
-{% hint style="info" %}
+:::info
For a full list of Forge hooks and usage examples, see the [hooks.md](../config/hooks.md "mention") documentation.
-{% endhint %}
+:::
-If you want to share a specific sequence of build hook logic, you can modularize your hook code into a **plugin** instead. This is how Forge's [webpack.md](../config/plugins/webpack.md "mention") works, for instance. For more details on authoring custom plugins, see the [writing-plugins.md](../advanced/extending-electron-forge/writing-plugins.md "mention") guide.
+If you want to share a specific sequence of build hook logic, you can modularize your hook code into a **plugin** instead. This is how Forge's [webpack.md](../config/plugins/webpack.mdx "mention") works, for instance. For more details on authoring custom plugins, see the [writing-plugins.md](../advanced/extending-electron-forge/writing-plugins.md "mention") guide.
## Cross-platform build systems
diff --git a/core-concepts/why-electron-forge.md b/docs/core-concepts/why-electron-forge.md
similarity index 100%
rename from core-concepts/why-electron-forge.md
rename to docs/core-concepts/why-electron-forge.md
diff --git a/guides/code-signing/README.md b/docs/guides/code-signing/README.md
similarity index 80%
rename from guides/code-signing/README.md
rename to docs/guides/code-signing/README.md
index 3c09bff..f875303 100644
--- a/guides/code-signing/README.md
+++ b/docs/guides/code-signing/README.md
@@ -8,10 +8,10 @@ Code signing is a security technology that you use to certify that an app was cr
This guide is split into two separate pages because there is a separate process for each platform:
-{% content-ref url="code-signing-macos.md" %}
+
[code-signing-macos.md](code-signing-macos.md)
-{% endcontent-ref %}
+
-{% content-ref url="code-signing-windows.md" %}
+
[code-signing-windows.md](code-signing-windows.md)
-{% endcontent-ref %}
+
diff --git a/guides/code-signing/code-signing-macos.md b/docs/guides/code-signing/code-signing-macos.md
similarity index 94%
rename from guides/code-signing/code-signing-macos.md
rename to docs/guides/code-signing/code-signing-macos.md
index f973412..1c04d81 100644
--- a/guides/code-signing/code-signing-macos.md
+++ b/docs/guides/code-signing/code-signing-macos.md
@@ -11,11 +11,11 @@ On macOS, there are two layers of security technology for application distributi
* **Code Signing** is the act of certifying the identity of the app's author and ensuring it was not tampered with before distribution.
* **Notarization** is an extra verification step where the app is sent to Apple servers for an automated malware scan.
-{% hint style="info" %}
+:::info
From macOS 10.15 (Catalina) onwards, your application needs to be **both code signed and notarized** to run on a user's machine without disabling additional operating system security checks.
The exception is for Mac App Store (MAS) apps, where notarization is not required because the MAS submission process involves a similar automated check.
-{% endhint %}
+:::
## Prerequisites
@@ -36,7 +36,7 @@ To sign Electron apps, you may require two separate certificates:
Once you have an Apple Developer Program membership, you first need to install them onto your machine. We recommend [loading them through Xcode](https://help.apple.com/xcode/mac/current/#/dev3a05256b8).
-{% hint style="success" %}
+:::info success
**Verifying your certificate is installed**
Once you have installed your certificate, you can check available code signing certificates in your terminal using the following shell command:
@@ -44,7 +44,7 @@ Once you have installed your certificate, you can check available code signing c
```shell
security find-identity -p codesigning -v
```
-{% endhint %}
+:::
## Configuring Forge
@@ -52,21 +52,20 @@ In Electron Forge, macOS apps are signed and notarized at the **Package** step b
### osxSign options
-{% hint style="info" %}
+:::info
Under the hood, Electron Forge uses the [`@electron/osx-sign`](https://github.com/electron/osx-sign) tool to sign your macOS application.
-{% endhint %}
+:::
To enable code signing on macOS, ensure that `packagerConfig.osxSign` exists in your Forge configuration.
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
packagerConfig: {
osxSign: {} // object must exist even if empty
}
};
```
-{% endcode %}
+
The `osxSign` config comes with defaults that work out of the box in most cases, so we recommend you start with an empty configuration object.
@@ -78,8 +77,7 @@ A common use case for modifying the default `osxSign` configuration is to custom
By default, the `@electron/osx-sign` tool comes with a set of entitlements that should work on both MAS or direct distribution targets. See the complete set of default entitlement files [on GitHub](https://github.com/electron/osx-sign/tree/main/entitlements).
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
packagerConfig: {
@@ -98,7 +96,7 @@ module.exports = {
// ...
};
```
-{% endcode %}
+
For further reading on entitlements, see the following pages in Apple developer documentation:
@@ -107,19 +105,19 @@ For further reading on entitlements, see the following pages in Apple developer
### osxNotarize options
-{% hint style="info" %}
+:::info
Under the hood, Electron Forge uses the [`@electron/notarize`](https://github.com/electron/notarize) tool to notarize your macOS application.
-{% endhint %}
+:::
The `osxNotarize` configuration object only supports `notarytool` as of Electron Forge v7.0.0.
The `notarytool` command has three authentication options, which are detailed below. Note that you will want to use a `forge.config.js` configuration so that you can load environment variables into your Forge config.
-{% hint style="danger" %}
+:::danger
**Keep your authentication details private**
You should never store authentication info in plaintext in your configuration. In the examples below, credentials are stored as environment variables and accessed via the Node.js [`process.env`](https://nodejs.org/dist/latest-v16.x/docs/api/process.html#processenv) object.
-{% endhint %}
+:::
#### Option 1: Using an app-specific password
@@ -133,8 +131,7 @@ There are two mandatory fields for `osxNotarize` if you are using this strategy:
| `appleIdPassword` | string | App-specific password |
| `teamId` | string | The Apple Team ID you want to notarize under. You can find Team IDs for team you belong to by going to [`https://developer.apple.com/account/#/membership`](https://developer.apple.com/account/#/membership) |
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
packagerConfig: {
@@ -149,11 +146,11 @@ module.exports = {
// ...
};
```
-{% endcode %}
-{% hint style="warning" %}
+
+:::warning
Despite the name, `appleIdPassword` is **not** the password for your Apple ID account.
-{% endhint %}
+:::
#### Option 2: Using an App Store Connect API key
@@ -167,8 +164,7 @@ There are three mandatory fields for `osxNotarize` if you are using this strateg
| `appleApiKeyId` | string | 10-character alphanumeric ID string. In the previous `AuthKey_ABCD123456.p8` example, this would be `ABCD123456`. |
| `appleApiIssuer` | string | UUID that identifies the API key issuer. You will find this ID in the "Keys" tab where you generated your API key. |
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
packagerConfig: {
@@ -183,7 +179,7 @@ module.exports = {
// ...
};
```
-{% endcode %}
+
#### Option 3: Using a keychain
@@ -202,8 +198,7 @@ There are two mandatory fields for `osxNotarize` if you are using this strategy:
| `keychain` | string | Name of (or path to) the keychain containing the profile with your credentials. |
| `keychainProfile` | string | Name of the keychain profile containing your notarization credentials. |
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
packagerConfig: {
@@ -217,14 +212,13 @@ module.exports = {
// ...
};
```
-{% endcode %}
+
### Example configuration
Below is a minimal Forge configuration for `osxSign` and `osxNotarize`.
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
packagerConfig: {
osxSign: {},
@@ -237,4 +231,4 @@ module.exports = {
}
};
```
-{% endcode %}
+
diff --git a/guides/code-signing/code-signing-windows.md b/docs/guides/code-signing/code-signing-windows.md
similarity index 94%
rename from guides/code-signing/code-signing-windows.md
rename to docs/guides/code-signing/code-signing-windows.md
index d58afaa..82df2f3 100644
--- a/guides/code-signing/code-signing-windows.md
+++ b/docs/guides/code-signing/code-signing-windows.md
@@ -6,11 +6,11 @@ description: >-
# Signing a Windows app
-{% hint style="warning" %}
+:::warning
Starting June 1, 2023 at 00:00 UTC, private keys for code signing certificates need to be stored on a hardware storage module compliant with FIPS 140 Level 2, Common Criteria EAL 4+ or equivalent.\
\
In practice, this means that software-based OV certificates used in the steps below will no longer be available for purchase. For instructions on how to sign applications with newer token-based certificates, consult your Certificate Authority's documentation.
-{% endhint %}
+:::
## Prerequisites
@@ -26,11 +26,11 @@ You can get a [Windows Authenticode](https://learn.microsoft.com/en-us/windows-h
* [Sectigo](https://sectigo.com/ssl-certificates-tls/code-signing)
* Amongst others, please shop around to find one that suits your needs! 😄
-{% hint style="danger" %}
+:::danger
**Keep your certificate password private**
Your certificate password should be a **secret**. Do not share it publicly or commit it to your source code.
-{% endhint %}
+:::
## Configuring Electron Forge
@@ -40,8 +40,7 @@ Once you have a Personal Information Exchange (`.pfx`) file for your certificate
For example, if you are creating a Squirrel.Windows installer:
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
packagerConfig: {},
makers: [
@@ -55,4 +54,4 @@ module.exports = {
]
};
```
-{% endcode %}
+
diff --git a/guides/create-and-add-icons.md b/docs/guides/create-and-add-icons.md
similarity index 89%
rename from guides/create-and-add-icons.md
rename to docs/guides/create-and-add-icons.md
index 40bfb9e..54ae511 100644
--- a/guides/create-and-add-icons.md
+++ b/docs/guides/create-and-add-icons.md
@@ -23,11 +23,11 @@ images/
└── icon@3x.png
```
-{% hint style="info" %}
+:::info
The following suffixes for DPI are also supported:
@1x, @1.25x, @1.33x, @1.4x, @1.5x, @1.8x, @2x, @2.5x, @3x, @4x, and @5x.
-{% endhint %}
+:::
### Supported formats
@@ -45,8 +45,7 @@ The recommended file formats and icon sizes for each platform are as follows:
Configuring the path to your icon can be done in your Forge configuration.
-{% code title="forge.config.js" %}
-```javascript
+```jsx title="forge.config.js"
module.exports = {
// ...
packagerConfig: {
@@ -55,11 +54,11 @@ module.exports = {
// ...
};
```
-{% endcode %}
-{% hint style="success" %}
+
+:::info success
Forge will automatically add the correct extension for each platform, so appending `.ico` or `.icns` to the path is not required.
-{% endhint %}
+:::
After the config has been updated, build your project to generate your executable with the Make command.
@@ -67,7 +66,8 @@ After the config has been updated, build your project to generate your executabl
Configuring the path to your icon must be done in both package.json as well as in Electron's main process.
-
module.exports = {
+```jsx
+module.exports = {
// ...
makers: \[
{
@@ -80,18 +80,20 @@ Configuring the path to your icon must be done in both package.json as well as i
}
]
// ...
-}
-
+}
+```
+
The icon must be additionally loaded when instantiating your [BrowserWindow](https://www.electronjs.org/docs/latest/api/browser-window#new-browserwindowoptions).
-
+ icon: '/path/to/icon.png'
+})
+```
Once the path to the icon has been configured, build your project to generate your executable with either `npm run make`.
@@ -101,7 +103,7 @@ Installers usually have icons! Don't forget to configure those in the Maker-spec
Here is an example of how that can be done:
-```javascript
+```jsx
// forge.config.js
module.exports = {
// ...
diff --git a/guides/developing-with-wsl.md b/docs/guides/developing-with-wsl.md
similarity index 97%
rename from guides/developing-with-wsl.md
rename to docs/guides/developing-with-wsl.md
index d6cb9da..b15ddb3 100644
--- a/guides/developing-with-wsl.md
+++ b/docs/guides/developing-with-wsl.md
@@ -31,7 +31,7 @@ For package/make/publish, you'll still need to specify the platform if you want
npm run make -- --platform=win32
```
-{% hint style="warning" %}
+:::warning
Some of the dependencies of Electron Forge don't quite work with WSL, as they don't detect that they're running in WSL _\(instead of Linux\)_ and thus tries to run certain tooling provided as Windows executables in... Wine. We are actively working on making the dependent tooling WSL-aware. The workaround is to run package/make/publish outside of WSL.
-{% endhint %}
+:::
diff --git a/guides/framework-integration/README.md b/docs/guides/framework-integration/README.md
similarity index 100%
rename from guides/framework-integration/README.md
rename to docs/guides/framework-integration/README.md
diff --git a/guides/framework-integration/parcel.md b/docs/guides/framework-integration/parcel.md
similarity index 100%
rename from guides/framework-integration/parcel.md
rename to docs/guides/framework-integration/parcel.md
diff --git a/guides/framework-integration/react-with-typescript.md b/docs/guides/framework-integration/react-with-typescript.mdx
similarity index 80%
rename from guides/framework-integration/react-with-typescript.md
rename to docs/guides/framework-integration/react-with-typescript.mdx
index 71c994a..a4ee23e 100644
--- a/guides/framework-integration/react-with-typescript.md
+++ b/docs/guides/framework-integration/react-with-typescript.mdx
@@ -2,13 +2,16 @@
description: How to create an Electron app with React, TypeScript, and Electron Forge
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# React with TypeScript
Adding React support to the TypeScript + Webpack template is fairly straightforward and doesn't require a complicated boilerplate to get started.
-{% hint style="info" %}
+:::info
The following guide has been tested with React 18, TypeScript 4.3, and Webpack 5.
-{% endhint %}
+:::
### Create the app and setup the TypeScript config
@@ -27,22 +30,29 @@ npm install --save-dev @types/react @types/react-dom
You should now be able to start writing and using React components in your Electron app. The following is a very minimal example of how to start to add React code:
-{% tabs %}
-{% tab title="src/app.tsx" %}
+
+
+
```tsx
import { createRoot } from 'react-dom/client';
const root = createRoot(document.body);
root.render(
Hello from React!
);
```
-{% endtab %}
+
-{% tab title="src/renderer.ts" %}
-```typescript
+
+
+```tsx
// Add this to the end of the existing file
import './app';
```
-{% endtab %}
-{% endtabs %}
+
+
For more about React, see [their documentation](https://react.dev/learn/add-react-to-an-existing-project).
diff --git a/guides/framework-integration/react.md b/docs/guides/framework-integration/react.mdx
similarity index 81%
rename from guides/framework-integration/react.md
rename to docs/guides/framework-integration/react.mdx
index ba2ce57..10f256f 100644
--- a/guides/framework-integration/react.md
+++ b/docs/guides/framework-integration/react.mdx
@@ -2,13 +2,16 @@
description: How to create an Electron app with React and Electron Forge
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# React
Adding React support to the Webpack template doesn't require a complicated boilerplate to get started.
-{% hint style="info" %}
+:::info
The following guide has been tested with React 18, Babel 7, and Webpack 5.
-{% endhint %}
+:::
### Create the app and setup the Webpack config
@@ -20,8 +23,7 @@ npm install --save-dev @babel/core @babel/preset-react babel-loader
Set up the [`babel-loader`](https://www.npmjs.com/package/babel-loader)module with the [React preset](https://babeljs.io/docs/en/babel-preset-react) in `webpack.rules.js`:
-{% code title="webpack.rules.js" %}
-```javascript
+```jsx title="webpack.rules.js"
module.exports = [
// ... existing loader config ...
{
@@ -37,7 +39,7 @@ module.exports = [
// ... existing loader config ...
];
```
-{% endcode %}
+
### Add the React dependencies
@@ -51,8 +53,14 @@ npm install --save react react-dom
You should now be able to start writing and using React components in your Electron app. The following is a very minimal example of how to start to add React code:
-{% tabs %}
-{% tab title="src/app.jsx" %}
+
+
+
```jsx
import * as React from 'react';
import { createRoot } from 'react-dom/client';
@@ -60,14 +68,15 @@ import { createRoot } from 'react-dom/client';
const root = createRoot(document.body);
root.render(
Hello from React!
);
```
-{% endtab %}
+
-{% tab title="src/renderer.js" %}
-```javascript
+
+
+```jsx
// Add this to the end of the existing file
import './app.jsx';
```
-{% endtab %}
-{% endtabs %}
+
+
For more about React, see their [documentation](https://react.dev/learn/add-react-to-an-existing-project).
diff --git a/guides/framework-integration/vue-3.md b/docs/guides/framework-integration/vue-3.mdx
similarity index 74%
rename from guides/framework-integration/vue-3.md
rename to docs/guides/framework-integration/vue-3.mdx
index 027c95b..f377120 100644
--- a/guides/framework-integration/vue-3.md
+++ b/docs/guides/framework-integration/vue-3.mdx
@@ -2,15 +2,18 @@
description: How to create an Electron app with Vue and Electron Forge
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# Vue 3
Vue 3 can be added to Electron Forge's Vite template with a few setup steps.
-{% hint style="info" %}
+:::info
The following guide has been tested with Vue 3 and Vite 4.
-{% endhint %}
+:::
## Setting up the app
@@ -33,8 +36,15 @@ npm install --save-dev @vitejs/plugin-vue
You should now be able to start using Vue components in your Electron app. The following is a very minimal example of how to start to add Vue 3 code:
-{% tabs %}
-{% tab title="src/index.html" %}
+
+
Replace the contents of `src/index.html` with a `
` element with the `#app` id attribute.
@@ -52,13 +62,13 @@ Replace the contents of `src/index.html` with a `
.png)