forge Documentation

1. Project Overview & Quickstart (electron/forge) Copy Chapter

File: README.md Copy Chapter

Electron Forge Copy Chapter

[!IMPORTANT]
We're currently beginning feature development for the next major version of Electron Forge, which is being done in the next branch.
To try out experimental pre-releases, install the @alpha dist-tag of the @electron-forge/* packages via npm.
For more details, see issue https://github.com/electron/forge/issues/4082.

A complete tool for building modern Electron applications.

Electron Forge unifies the existing (and well maintained) build tools for
Electron development into a simple, easy to use package so that anyone can
jump right in to Electron development.

Website |
Goals |
Docs and Usage |
Configuration |
Support |
Contributing

Getting Started

Pre-requisites:

• Node 16.4.0 or higher
• Git

You can initialize an Electron Forge project with the create-electron-app
CLI tool.

npx create-electron-app@latest my-new-app

# then
cd my-new-app
npm start

For more information on creating a new project from a template, see our CLI documentation.

Docs and Usage

For Electron Forge documentation and usage you should check out our website:
electronforge.io

Project Goals

1. Starting with Electron should be as simple as a single command.
2. Developers shouldn't have to worry about setting up build tooling,
   native module rebuilding, etc. Everything should "just work" for them out
   of the box.
3. Everything from creating the project to packaging the project for release
   should be handled by one core dependency in a standard way while still offering
   users maximum choice and freedom.

With these goals in mind, under the hood this project uses, among others:

• @electron/rebuild:
  Automatically recompiles native Node.js modules against the correct
  Electron version.
• @electron/packager:
  Customizes and bundles your Electron app to get it ready for distribution.

Contributing Copy Chapter

If you are interested in reporting/fixing issues and contributing directly to the code base, please see CONTRIBUTING.md for more information on what we're looking for and how to get started.

Community Copy Chapter

Please report bugs or feature requests in our issue tracker.
You can find help for debugging your Electron Forge on the Support page, and ask questions in the official Electron Discord server, where there is a dedicated channel for Electron Forge.

File: packages/utils/web-multi-logger/README.md Copy Chapter

Web Multi Logger

Display multiple streams of logs in one window

This module allows you to pipe multiple logically separated streams of logs into
multiple visually separated views in a web console. It comes with full ANSI
support so you can pipe anything that would work in a Terminal into this tool
as well.

Usage Copy Chapter

import Logger from '@electron-forge/web-multi-logger';

const logger = new Logger();

const serverTab = logger.createTab('server');
const frontEndTab = logger.createTab('front_end');

runServerWithLogger(serverTab);
runFrontEndWithLogger(frontEndTab);

// Navigate to http://localhost:9000 in your browser

File: packages/publisher/snapcraft/README.md Copy Chapter

publisher-snapcraft Copy Chapter

The Snapcraft target publishes your .snap artifacts to the Snap Store. All configuration of your package is done via the Snapcraft maker.

This target requires that the system has the snapcraft utility installed.

Configuration options are documented in PublisherSnapConfig.

module.exports = {
  // ...
  publishers: [
    {
      name: '@electron-forge/publisher-snapcraft',
      config: {
        release: 'latest/edge, insider/stable'
      }
    }
  ]
};

File: packages/publisher/s3/README.md Copy Chapter

publisher-s3 Copy Chapter

@electron-forge/publisher-s3 publishes all your artifacts to an Amazon S3 bucket where users will be able to download them.

By default, all files are positioned at the following key:

${config.folder || appVersion}/${artifactName}

Configuration options are documented in PublisherS3Config.

module.exports = {
  // ...
  publishers: [
    {
      name: '@electron-forge/publisher-s3',
      config: {
        bucket: 'my-bucket',
        public: true
      }
    }
  ]
};

If you run publish twice with the same version on the same platform, it is possible for your old artifacts to get overwritten in S3. It is your responsibility to ensure that you don't overwrite your own releases.

Authentication Copy Section

It is recommended to follow the Amazon AWS guide and set either a shared credentials guide or the proper environment variables. However, if that is not possible, the publisher config allows the setting of the accessKeyId and secretAccessKey configuration options.

File: packages/publisher/nucleus/README.md Copy Chapter

publisher-nucleus Copy Chapter

@electron-forge/publisher-nucleus publishes all your artifacts to an instance of Nucleus Update Server where users will be able to download them. This update service supports all three platforms.

Check out the README at atlassian/nucleus for more information on this project.

Configuration options are documented in [`Publisher
NucleusConfig](https://js.electronforge.io/interfaces/_electron_forge_publisher_nucleus.PublisherNucleusConfig.html).

module.exports = {
  // ...
  publishers: [
    {
      name: '@electron-forge/publisher-nucleus',
      config: {
        host: 'https://my-nucleus.mysite.com',
        appId: 1,
        channelId: 'abcdefg',
        token: 'my-token'
      }
    }
  ]
};

We recommend you set the tokenoption using an environment variable, don't hard code into in your config.

File: packages/publisher/github/README.md Copy Chapter

publisher-github Copy Chapter

@electron-forge/publisher-github publishes all your artifacts to GitHub releases, this allows your users to download the files straight from your repository or if your repository is open source you can use update.electronjs.org and get a free hosted update service.

Configuration options are documented in PublisherGithubConfig.

module.exports = {
  // ...
  publishers: [
    {
      name: '@electron-forge/publisher-github',
      config: {
          owner: 'me',
          name: 'awesome-thing'
        },
        prerelease: true
      }
    }
  ]
};

File: packages/publisher/electron-release-server/README.md Copy Chapter

publisher-electron-release-server Copy Chapter

@electron-forge/publisher-electron-release-server publishes all your artifacts to a hosted instance of Electron Release Server where users will be able to download them.

Please note that Electron Release Server is a community powered project and is not associated with Electron Forge or the Electron project directly.

Configuration options are documented in PublisherERSConfig.

module.exports = {
  // ...
  publishers: [
    {
      name: '@electron-forge/publisher-electron-release-server',
      config: {
        baseUrl: 'https://update.server.com',
        username: 'admin',
        password: 'admin'
      }
    }
  ]
};

File: packages/publisher/bitbucket/README.md Copy Chapter

Electron Forge: publisher-bitbucket Copy Chapter

@electron-forge/publisher-bitbucket publishes your artifacts to Bitbucket where users will be able to download them.

This publish target is for Bitbucket Cloud only and will not work with self hosted Bitbucket Server instances.

Configuration options are documented in PublisherBitbucketConfig.

module.exports = {
  // ...
  publishers: [
    {
      name: '@electron-forge/publisher-bitbucket',
      config: {
          owner: 'myusername',
          name: 'myreponame'
        },
        auth: {
          username: 'myusername',
          appPassword: 'mysecretapppassword'
        }
      }
    }
  ]
};

Alternatively you can (and should) use environment variables for the authentication

# env.sh
BITBUCKET_USERNAME="myusername"
BITBUCKET_APP_PASSWORD="mysecretapppassword"

source env.sh

File: packages/plugin/webpack/README.md Copy Chapter

plugin-webpack Copy Chapter

This plugin makes it easy to set up standard webpack tooling to compile both your main process code and your renderer process code, with built-in support for Hot Module Replacement (HMR) in the renderer process and support for multiple renderers.

// forge.config.js

module.exports = {
  plugins: [
    {
      name: '@electron-forge/plugin-webpack',
      config: {
        mainConfig: './webpack.main.config.js',
        renderer: {
          config: './webpack.renderer.config.js',
          entryPoints: [{
            name: 'main_window',
            html: './src/renderer/index.html',
            js: './src/renderer/index.js',
            preload: {
              js: './src/preload.js'
            }
          }]
        }
      }
    }
  ]
};

File: packages/plugin/vite/README.md Copy Chapter

plugin-vite Copy Chapter

Note: This plugin is considered experimental and is under active development; we do not offer API stability guarantees as development continues. Minor versions may include breaking changes - see release notes for details on migration.

This plugin makes it easy to set up standard vite tooling to compile both your main process code and your renderer process code, with built-in support for Hot Module Replacement (HMR) in the renderer process and support for multiple renderers.

// forge.config.js

module.exports = {
  plugins: [
    {
      name: '@electron-forge/plugin-vite',
      config: {
        // `build` can specify multiple entry builds, which can be Main process, Preload scripts, Worker process, etc.
        // If you are familiar with Vite configuration, it will look really familiar.
        build: [
          {
            // `entry` is just an alias for `build.lib.entry` in the corresponding file of `config`.
            entry: 'src/main.js',
            config: 'vite.main.config.mjs'
          },
          {
            entry: 'src/preload.js',
            config: 'vite.preload.config.mjs'
          }
        ],
        renderer: [
          {
            name: 'main_window',
            config: 'vite.renderer.config.mjs'
          }
        ]
      }
    }
  ]
};

2. Official Technical Reference & Guides (electron/update.electronjs.org) Copy Chapter

📡 update.electronjs.org

A free service that makes it easy for open-source Electron apps to update themselves.

Requirements Copy Chapter

Before using this service, make sure your Electron app meets these criteria:

• Your app runs on macOS or Windows
• Your app has a public GitHub repository
• Your builds are published to GitHub Releases
• Your builds are code signed (macOS and MSIX only)

Quick Setup Copy Chapter

We provide update-electron-app as a zero-config runtime dependency to use update.electronjs.org
with your Electron app.

npm install update-electron-app

Call it from in your main process file:

require('update-electron-app')()

And that's all it takes! To customize, see the update-electron-app API.

Once your application is packaged,
it will update itself for each new
GitHub Release that you
publish.

Manual Setup Copy Chapter

Use something like the following setup to add automatic updates to your application:

[!IMPORTANT]
Please ensure that the code below will only be executed in
your packaged app, and not in development. You can use
the app.isPackaged API
to check for the environment.

const { app, autoUpdater } = require('electron')

Next, construct the URL of the update server and tell
autoUpdater about it:

const server = 'https://update.electronjs.org'
const feed = `${server}/OWNER/REPO/${process.platform}-${process.arch}/${app.getVersion()}`

autoUpdater.setFeedURL(feed)

As the final step, check for updates. The example below will check every 10
minutes:

setInterval(() => {
  autoUpdater.checkForUpdates()
}, 10 * 60 * 1000)

Once your application is packaged,
it will update itself for each new
GitHub Release that you
publish.

Routes Copy Chapter

The following API endpoints are available:

• /:owner/:repo/:platform/:version
• /:owner/:repo/:platform-:arch/:version
• /:owner/:repo/:platform/:format/:version
• /:owner/:repo/:platform-:arch/:format/:version
• /:owner/:repo/:platform/:version/RELEASES

These API endpoints support the query path arguments as defined below:

• :owner - GitHub repository owner (organization or user)
• :repo - GitHub repository name
• :platform - Platform type
  • Windows: win32
  • macOS: darwin
• :arch - Architecture type
  • Windows: x64, ia32, arm64
  • macOS: x64, arm64, universal
• :format - (Optional) Update format type
  • squirrel - Squirrel.Windows (default for Windows when omitted)
  • msix - MSIX auto-update (available on Electron 41+)
• :version - Semantic Versioning (SemVer) compatible application version number

Asset Naming Convention Copy Chapter

This project supports specific naming conventions for GitHub Releases assets.

The following heuristics are used to identify update availability for a specific platform and architecture:

macOS Assets Copy Section

• Asset must be a .zip file.
• Asset name must include one of the following platform identifiers: -mac, -darwin, or -osx.
• Asset name may specify the architecture (if not specified, will default to -x64):
  • -arm64 for Apple Silicon.
  • -x64 for Intel-based macOS.
  • -universal for Universal binaries.

Example asset names:

• app-mac-arm64-0.0.1.zip
• app-mac-arm64.zip
• app-0.0.1-osx-x64.zip
• app-osx-x64.zip
• app-darwin-universal.zip
• app-mac.zip (no architecture specified - treated as -x64)

Windows Assets (Squirrel) Copy Section

• Asset must be a .zip or .exe file.
• Asset name must include the -win32 platform identifier.
• Asset name may specify the architecture (if not specified, will default to -x64):
  • -ia32 for 32-bit Windows.
  • -x64 for 64-bit Windows.
  • -arm64 for ARM-based Windows.
• .exe files without specific architecture tags or the -win32 platform identifier are assumed to be -x64 by default.

Example asset names:

• app-win32-ia32-0.0.1.zip
• app-win32-ia32.zip
• app-0.0.1-win32-x64.zip
• app-win32-x64.zip
• app-win32-arm64.zip
• app-win32-arm64.exe
• app-win32-arm64-v1.2.3.exe
• app-win32.exe (no architecture specified - treated as -x64)
• app-installer.exe (generic .exe file with no architecture or platform identifier specified - treated as -x64)

Windows Assets (MSIX) Copy Section

• Asset must be a .msix file.
• Asset name must include the -win32 platform identifier.
• Asset name may specify the architecture (if not specified, will default to -x64):
  • -x64 for 64-bit Windows.
  • -arm64 for ARM-based Windows.
• .msix files without specific architecture tags or the -win32 platform identifier are assumed to be -x64 by default.

Example asset names:

• app-win32-x64.msix
• app-1.0.0-win32-x64.msix
• app-win32-arm64.msix
• app-win32.msix (no architecture specified - treated as -x64)
• app-installer.msix (generic .msix file with no architecture or platform identifier specified - treated as -x64)

To use MSIX updates, include the msix format segment in the update feed URL:

const server = 'https://update.electronjs.org'
const feed = `${server}/OWNER/REPO/${process.platform}-${process.arch}/msix/${app.getVersion()}`

autoUpdater.setFeedURL(feed)

The MSIX updater returns the same JSON format as macOS ({ name, notes, url }) and does not use the RELEASES endpoint.

Development Copy Chapter

There are two development servers available:

Production server Copy Section

This runs the full server with Redis caching and GitHub API integration.

You'll first need to have a running Redis server. There are two options:

1. Locally: Install Redis locally and run it directly with redis-server. Learn how to install Redis on the Redis website.
2. Docker: Install and run Redis with docker run -p 6379:6379 -it redis/redis-stack-server:latest.

Then run the server:

yarn
GH_TOKEN=TOKEN yarn start

Test server Copy Section

This runs a lightweight server with an in-memory cache and no external dependencies (no Redis or GH_TOKEN required).
Useful for local development and testing.

yarn
yarn start-test-server

Sample app Copy Section

To try with an actual electron app, run:

yarn start &
cd example
yarn

On Darwin:

yarn build
./out/test-darwin-x64/test.app/Contents/MacOS/test

On Windows:

yarn run build
"example\out\make\squirrel.windows\x64\test-0.0.0 Setup.exe"