## 1. Project Overview & Quickstart (electron/forge)

## File: README.md

## Electron Forge

[](https://github.com/electron/forge/actions/workflows/ci.yml)
[](https://discord.com/invite/APGC3k5yaH)
[](https://npm.im/@electron-forge/cli)
[](https://github.com/electron/forge/blob/main/LICENSE)


> [!IMPORTANT]
> We're currently beginning feature development for the next major version of Electron Forge, which is being done in the [`next`](https://github.com/electron/forge/tree/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](https://www.electronforge.io) |
[Goals](#project-goals) |
[Docs and Usage](#docs-and-usage) |
[Configuration](https://www.electronforge.io/configuration) |
[Support](https://github.com/electron/forge/blob/main/SUPPORT.md) |
[Contributing](https://github.com/electron/forge/blob/main/CONTRIBUTING.md)

---

# Getting Started

Pre-requisites:

- Node 16.4.0 or higher
- Git

You can initialize an Electron Forge project with the [`create-electron-app`](https://www.npmjs.com/package/create-electron-app)
CLI tool.

```bash
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](https://www.electronforge.io/cli).

# Docs and Usage

For Electron Forge documentation and usage you should check out our website:
[electronforge.io](https://www.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`](https://github.com/electron/rebuild):
  Automatically recompiles native Node.js modules against the correct
  Electron version.
- [`@electron/packager`](https://github.com/electron/packager):
  Customizes and bundles your Electron app to get it ready for distribution.

## Contributing

If you are interested in reporting/fixing issues and contributing directly to the code base, please see [CONTRIBUTING.md](https://github.com/electron/forge/blob/main/CONTRIBUTING.md) for more information on what we're looking for and how to get started.

## Community

Please report bugs or feature requests in our [issue tracker](https://github.com/electron/forge/issues).
You can find help for debugging your Electron Forge on the [Support page](https://github.com/electron/forge/blob/main/SUPPORT.md), and ask questions in the [official Electron Discord server](https://discord.gg/invite/APGC3k5yaH), where there is a dedicated channel for Electron Forge.

---

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

# 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

```javascript
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

## publisher-snapcraft

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](https://js.electronforge.io/interfaces/_electron_forge_publisher_snapcraft.PublisherSnapcraftConfig.html).

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

---

## File: packages/publisher/s3/README.md

## publisher-s3

`@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](https://js.electronforge.io/interfaces/_electron_forge_publisher_s3.PublisherS3Config.html).

```javascript title=forge.config.js
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

It is recommended to follow the [Amazon AWS guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html) and set either a shared credentials guide or the proper environment variables. However, if that is not possible, the publisher config allows the setting of the accessKeyId and secretAccessKey configuration options.

---

## File: packages/publisher/nucleus/README.md

## publisher-nucleus

`@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`](https://github.com/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).

```javascript title=forge.config.js
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 `token`option using an environment variable, don't hard code into in your config.

---

## File: packages/publisher/github/README.md

## publisher-github

`@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](https://github.com/electron/update.electronjs.org) and get a free hosted update service.

Configuration options are documented in [`PublisherGithubConfig`](https://js.electronforge.io/interfaces/_electron_forge_publisher_github.PublisherGitHubConfig.html).

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

---

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

## publisher-electron-release-server

`@electron-forge/publisher-electron-release-server` publishes all your artifacts to a hosted instance of [Electron Release Server](https://github.com/ArekSredzki/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`](https://js.electronforge.io/interfaces/_electron_forge_publisher_electron_release_server.PublisherERSConfig.html).

```javascript title=forge.config.js
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

## Electron Forge: publisher-bitbucket

`@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`](https://js.electronforge.io/interfaces/_electron_forge_publisher_bitbucket.PublisherBitbucketConfig.html).

```javascript title=forge.config.js
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

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

```sh
source env.sh
```

---

## File: packages/plugin/webpack/README.md

## plugin-webpack

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.

```javascript
// 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

## plugin-vite

_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.

```javascript
// 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)

# 📡 update.electronjs.org

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

[](https://github.com/electron/update.electronjs.org/actions/workflows/test.yml)

## Requirements

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

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

```sh
npm install update-electron-app
```

Call it from in your [main process] file:

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

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

Once your application is [packaged](https://electronjs.org/docs/tutorial/application-distribution),
it will update itself for each new
[GitHub Release](https://help.github.com/articles/creating-releases/) that you
publish.

## Manual Setup

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](https://www.electronjs.org/docs/latest/api/app#appispackaged-readonly) API
> to check for the environment.

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

Next, construct the URL of the update server and tell
[autoUpdater](https://electronjs.org/docs/latest/api/auto-updater) about it:

```javascript
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:

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

Once your application is [packaged](https://electronjs.org/docs/tutorial/application-distribution),
it will update itself for each new
[GitHub Release](https://help.github.com/articles/creating-releases/) that you
publish.

## Routes

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

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

- 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)

- 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)

- 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:

```javascript
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

There are two development servers available:

### Production server

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](https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/).
2) Docker: Install and run Redis with `docker run -p 6379:6379 -it redis/redis-stack-server:latest`.

Then run the server:

```bash
yarn
GH_TOKEN=TOKEN yarn start
```

### Test server

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.

```bash
yarn
yarn start-test-server
```

### Sample app

To try with an actual electron app, run:

```bash
yarn start &
cd example
yarn
```

On Darwin:

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

On Windows:

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

[update-electron-app API]: https://github.com/electron/update-electron-app#api
[update-electron-app]: https://github.com/electron/update-electron-app
[main process]: https://electronjs.org/docs/glossary#main-process
[code signed]: https://github.com/electron/electron/blob/main/docs/tutorial/code-signing.md