/desktop-packaging-electron-forge

name: desktop-packaging-electron-forge
description: Electron Forge build toolchain -- makers, publishers, code signing, fuses, hooks, CI/CD packaging

Electron Forge Packaging

> **Quick Guide:** Electron Forge v7 is the official Electron build toolchain. Configure via `forge.config.ts` with typed imports from `@electron-forge/shared-types`. Use **makers** to produce platform-specific installers (Squirrel for Windows, DMG/ZIP for macOS, deb/rpm for Linux). Use **publishers** to upload artifacts (GitHub Releases, S3, Snapcraft). Always code-sign production builds -- macOS requires both signing and notarization. Enable Electron **Fuses** to harden the binary at package time. Use **hooks** (`prePackage`, `postMake`) for custom build logic. Electron itself MUST be a `devDependency` -- Forge bundles only `dependencies`.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST place `electron` in `devDependencies` -- Forge provides the Electron binary during packaging; placing it in `dependencies` bloats the app by ~200MB)**

**(You MUST code-sign macOS builds with `osxSign` and `osxNotarize` in `packagerConfig` -- unsigned apps are blocked by Gatekeeper on macOS 10.15+)**

**(You MUST enable `asar: true` in `packagerConfig` -- without ASAR, your source code ships as plain-text files readable by any user)**

**(You MUST store signing credentials in environment variables -- never hardcode secrets in `forge.config.ts`)**

**(You MUST enable Fuses (`FuseV1Options.RunAsNode: false`, `OnlyLoadAppFromAsar: true`) for production security -- without them, attackers can bypass ASAR integrity and run arbitrary Node.js code)**

</critical_requirements>

---

**Auto-detection:** Electron Forge, electron-forge, forge.config.ts, forge.config.js, @electron-forge, maker-squirrel, maker-dmg, maker-deb, maker-rpm, maker-zip, maker-flatpak, maker-snap, maker-appx, maker-wix, maker-pkg, maker-msix, publisher-github, publisher-s3, publisher-snapcraft, plugin-vite, plugin-webpack, plugin-fuses, FusesPlugin, osxSign, osxNotarize, electron-forge make, electron-forge publish, electron-forge package

**When to use:**

• Configuring `forge.config.ts` for packaging and distribution
• Choosing and configuring makers for target platforms
• Setting up publishers for automated release distribution
• Code signing macOS (notarization) or Windows (Authenticode) builds
• Enabling Electron Fuses for binary hardening
• Adding build hooks for custom pre/post-packaging logic
• Setting up CI/CD pipelines for cross-platform builds
• Deciding between Electron Forge and electron-builder

**When NOT to use:**

• Electron app architecture (main/renderer process, IPC, preload) -- use the Electron framework skill
• Choosing or configuring a bundler for renderer code in isolation
• Auto-update implementation (that is an Electron framework concern, not a Forge concern)
• UI framework selection for renderers

**Key patterns covered:**

• forge.config.ts structure with typed configuration
• Platform-specific maker selection and configuration
• macOS code signing + notarization setup
• Windows Authenticode signing (traditional + Azure Trusted Signing)
• Fuses plugin for binary hardening
• Publisher configuration (GitHub, S3, Snapcraft)
• Build hooks and lifecycle
• CI/CD cross-platform build matrix
• Forge vs electron-builder decision framework

---

<philosophy>

Philosophy

Electron Forge is a **unified build pipeline** that composes first-party Electron tools (`@electron/packager`, `@electron/rebuild`, `@electron/osx-sign`, `@electron/notarize`, `@electron/fuses`) into a single workflow. Rather than reimplementing build logic, Forge orchestrates existing tools through three steps:

1. **Package** -- `@electron/packager` creates the platform-specific app bundle (.app, .exe) 2. **Make** -- Makers transform the bundle into distributable installers (.dmg, .msi, .deb) 3. **Publish** -- Publishers upload make artifacts to distribution targets (GitHub, S3)

**Why Forge over alternatives:**

• First-party: maintained by the Electron team, receives new features (ASAR integrity, universal macOS builds) as soon as they ship
• Composable: makers, publishers, and plugins are independent npm packages
• TypeScript-native: `forge.config.ts` with full type inference since v7

**Key constraint:** Forge runs makers only for the current host OS by default. Cross-platform builds require CI/CD with per-platform runners (macOS for .dmg, Windows for .exe, Linux for .deb).

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: forge.config.ts Structure

The configuration file defines packaging options, makers, publishers, plugins, and hooks. All fields are optional.

import type { ForgeConfig } from "@electron-forge/shared-types";
import { FusesPlugin } from "@electron-forge/plugin-fuses";
import { FuseV1Options, FuseVersion } from "@electron/fuses";

const config: ForgeConfig = {
  packagerConfig: {
    asar: true,
    icon: "./assets/icon", // omit extension -- Forge picks .icns/.ico/.png
    name: "MyApp",
    executableName: "my-app",
    appBundleId: "com.example.myapp",
  },
  makers: [/* see Pattern 2 */],
  publishers: [/* see Pattern 5 */],
  plugins: [/* see Pattern 4 */],
  hooks: {/* see Pattern 6 */},
};

export default config;

**Key constraint:** You cannot override `dir`, `arch`, `platform`, `out`, or `electronVersion` in `packagerConfig` -- Forge sets these internally.

See [examples/core.md](examples/core.md) for full configuration with makers, signing, and fuses.

---

Pattern 2: Maker Selection by Platform

Each maker produces a specific installer format for a target OS. Install only the makers you need.

| Maker | Package | Platform | Output | |-------|---------|----------|--------| | Squirrel.Windows | `@electron-forge/maker-squirrel` | Wind