Claude Skill

desktop-packaging-electron-forge

Electron Forge build toolchain -- makers, publishers, code signing, fuses, hooks, CI/CD packaging

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_desktop-packaging-electron-forge_skills_desktop-packaging-electron-forge-707467a.zip · 18 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/desktop-packaging-electron-forge/skills/desktop-packaging-electron-forge
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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

(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



<decision_framework>

Decision Framework

Forge vs electron-builder

Choosing a build tool?
+-- Want first-party Electron support (ASAR integrity, universal macOS)?
|   +-- YES --> Electron Forge (receives features same-day as Electron)
+-- Need YAML-based config, NSIS installer, or broad community support?
|   +-- YES --> electron-builder (more installer targets, larger community)
+-- Need maximum customization for enterprise?
|   +-- YES --> electron-builder (more config options, NSIS scripting)
+-- Starting a new project?
    +-- YES --> Electron Forge (official recommendation, TypeScript config)
Factor Electron Forge electron-builder
Maintainer Electron team Community
Config format TypeScript / JavaScript YAML / JSON / JS
New Electron features Same-day Delayed
Plugin ecosystem Makers, publishers, plugins Built-in monolith
Windows installers Squirrel, WiX, MSIX, AppX NSIS, Squirrel, MSI, AppX
macOS installers DMG, ZIP, PKG DMG, ZIP, PKG, MAS
npm downloads ~50K/week ~1.4M/week
Architecture Composable packages Monolithic

Maker Selection

Which maker for your platform?
+-- Windows?
|   +-- Auto-updating desktop app --> Squirrel.Windows
|   +-- Enterprise/IT deployment --> WiX MSI
|   +-- Microsoft Store --> AppX or MSIX
+-- macOS?
|   +-- Direct distribution --> DMG (drag-to-install) + ZIP (for auto-updater)
|   +-- Mac App Store --> PKG
+-- Linux?
|   +-- Debian/Ubuntu --> deb
|   +-- Fedora/RHEL --> RPM
|   +-- Universal sandboxed --> Flatpak or Snap

</decision_framework>


Detailed resources:

  • examples/core.md -- forge.config.ts setup, makers, Vite plugin, fuses, dependency management
  • examples/signing.md -- macOS notarization, Windows Authenticode, Azure Trusted Signing, entitlements
  • examples/publishers.md -- GitHub, S3, Snapcraft publishers with CI/CD patterns
  • examples/hooks.md -- Build lifecycle hooks, custom makers, extending Forge
  • reference.md -- Maker/publisher quick-reference tables, fuse options, CLI commands, Forge vs builder comparison

<red_flags>

RED FLAGS

Critical Issues:

  • Placing electron in dependencies instead of devDependencies -- bloats the packaged app by ~200MB because Forge already provides the binary
  • Shipping without code signing -- macOS Gatekeeper blocks unsigned apps entirely; Windows SmartScreen shows scary warnings
  • Hardcoding signing credentials in forge.config.ts -- secrets end up in version control; always use process.env
  • Not enabling ASAR (asar: false) -- ships your source code as readable plain-text files
  • Not setting RunAsNode: false fuse -- allows ELECTRON_RUN_AS_NODE=1 to execute arbitrary code with your app's permissions

Architecture Issues:

  • Running electron-forge make on macOS expecting Windows .exe output -- makers run only on the target OS (use CI/CD with per-platform runners)
  • Placing native modules (better-sqlite3, sharp) inside ASAR without asarUnpack -- native addons cannot load from inside an ASAR archive
  • Not running @electron/rebuild for native modules -- modules compiled for system Node.js crash in Electron's Node.js runtime (Forge runs rebuild automatically during package, but manual installs need it)
  • Using electron-forge package for distribution -- this produces an uninstallable app bundle; use make for distributable installers

Configuration Mistakes:

  • Setting asar: true without asarUnpack for native modules -- the app will crash at runtime trying to load the native addon
  • Forgetting the platforms array on makers -- maker runs on all platforms and fails on unsupported ones
  • Using osxNotarize without osxSign -- notarization requires a signed binary; Apple rejects unsigned submissions
  • Using your Apple ID password instead of an app-specific password for osxNotarize -- regular passwords are rejected when 2FA is enabled

Gotchas & Edge Cases:

  • electron-forge start in dev mode does not run makers -- dev mode uses unpackaged source; always test with make before release
  • Notarization takes 2-10 minutes per build -- factor this into CI/CD timeout settings
  • Squirrel.Windows handles first-run events (shortcuts, desktop icons) -- your main process must handle Squirrel startup events or the app opens multiple times during install
  • __dirname resolves to virtual ASAR paths in packaged builds -- use app.isPackaged + process.resourcesPath for resource file paths
  • The Vite plugin is experimental since v7.5.0 -- minor version bumps may include breaking changes to its config shape
  • Azure Trusted Signing paths must not contain spaces -- signing fails silently if any path has spaces
  • Forge hooks run in parallel, not sequentially -- do not rely on execution order between hooks of the same type

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

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

Failure to follow these rules will produce insecure, bloated, or unsigned builds that OS security mechanisms will block or warn users about.

</critical_reminders>

Files (skills)
  • examples
    • core.md 6.7 KB
      Loading…
    • hooks.md 4.7 KB
      Loading…
    • publishers.md 4.8 KB
      Loading…
    • signing.md 6 KB
      Loading…
  • reference.md 10 KB
    Loading…
  • SKILL.md 19 KB
    ---
    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
    
    **(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.
    
    ```typescript
    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` | Windows      | `.exe` (auto-updating)    |
    | WiX MSI          | `@electron-forge/maker-wix`      | Windows      | `.msi`                    |
    | MSIX             | `@electron-forge/maker-msix`     | Windows      | `.msix`                   |
    | AppX             | `@electron-forge/maker-appx`     | Windows      | `.appx` (Microsoft Store) |
    | DMG              | `@electron-forge/maker-dmg`      | macOS        | `.dmg`                    |
    | PKG              | `@electron-forge/maker-pkg`      | macOS        | `.pkg` (Mac App Store)    |
    | ZIP              | `@electron-forge/maker-zip`      | macOS, Linux | `.zip`                    |
    | deb              | `@electron-forge/maker-deb`      | Linux        | `.deb` (Debian/Ubuntu)    |
    | RPM              | `@electron-forge/maker-rpm`      | Linux        | `.rpm` (Fedora/RHEL)      |
    | Flatpak          | `@electron-forge/maker-flatpak`  | Linux        | `.flatpak`                |
    | Snap             | `@electron-forge/maker-snap`     | Linux        | `.snap`                   |
    
    **Recommended starter set:** Squirrel (Windows) + DMG + ZIP (macOS) + deb (Linux).
    
    See [examples/core.md](examples/core.md) for maker configuration examples.
    
    ---
    
    ### Pattern 3: Code Signing
    
    macOS and Windows both require code signing for distribution. Without it, OS security warnings block or discourage installation.
    
    #### macOS (Sign + Notarize)
    
    ```typescript
    packagerConfig: {
      osxSign: {},  // empty object activates defaults -- signs with first valid identity
      osxNotarize: {
        appleId: process.env.APPLE_ID,
        appleIdPassword: process.env.APPLE_PASSWORD,  // app-specific password, NOT Apple ID password
        teamId: process.env.APPLE_TEAM_ID,
      },
    },
    ```
    
    **Requirements:** Apple Developer Program membership, "Developer ID Application" certificate in Keychain, `hardenedRuntime: true` (required for notarization).
    
    #### Windows (Authenticode)
    
    ```typescript
    // Squirrel maker with traditional certificate
    {
      name: "@electron-forge/maker-squirrel",
      config: {
        certificateFile: process.env.WIN_CSC_LINK,
        certificatePassword: process.env.WIN_CSC_KEY_PASSWORD,
      },
    },
    ```
    
    **Key point:** Since June 2023, private keys for code signing certificates must be stored on FIPS 140 Level 2 hardware. Azure Trusted Signing is the modern alternative for Windows -- see [examples/signing.md](examples/signing.md).
    
    See [examples/signing.md](examples/signing.md) for full signing configuration, notarization strategies, and Azure Trusted Signing setup.
    
    ---
    
    ### Pattern 4: Fuses Plugin (Binary Hardening)
    
    Fuses are bits in the Electron binary flipped at package time to enable/disable features permanently.
    
    ```typescript
    import { FusesPlugin } from "@electron-forge/plugin-fuses";
    import { FuseV1Options, FuseVersion } from "@electron/fuses";
    
    plugins: [
      new FusesPlugin({
        version: FuseVersion.V1,
        [FuseV1Options.RunAsNode]: false,
        [FuseV1Options.EnableCookieEncryption]: true,
        [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
        [FuseV1Options.EnableNodeCliInspectArguments]: false,
        [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
        [FuseV1Options.OnlyLoadAppFromAsar]: true,
        [FuseV1Options.GrantFileProtocolExtraPrivileges]: false,
      }),
    ],
    ```
    
    **Why critical:** Without `RunAsNode: false`, attackers can set `ELECTRON_RUN_AS_NODE=1` and run arbitrary code. Without `OnlyLoadAppFromAsar: true`, ASAR integrity validation can be bypassed by placing files alongside the archive.
    
    **Verification:** `npx @electron/fuses read --app /path/to/packaged/app`
    
    See [examples/core.md](examples/core.md) for the full fuses configuration with explanations.
    
    ---
    
    ### Pattern 5: Publishers
    
    Publishers upload make artifacts to distribution targets.
    
    ```typescript
    publishers: [
      {
        name: "@electron-forge/publisher-github",
        config: {
          repository: { owner: "my-org", name: "my-app" },
          prerelease: true,
        },
      },
    ],
    ```
    
    | Publisher | Package                               | Target               |
    | --------- | ------------------------------------- | -------------------- |
    | GitHub    | `@electron-forge/publisher-github`    | GitHub Releases      |
    | S3        | `@electron-forge/publisher-s3`        | Amazon S3 bucket     |
    | Snapcraft | `@electron-forge/publisher-snapcraft` | Snap Store           |
    | GCS       | `@electron-forge/publisher-gcs`       | Google Cloud Storage |
    
    **Authentication:** Use `GITHUB_TOKEN` env var for GitHub publisher. Use AWS credentials (env vars or shared credentials file) for S3.
    
    See [examples/publishers.md](examples/publishers.md) for publisher configuration with CI/CD integration.
    
    ---
    
    ### Pattern 6: Build Hooks
    
    Hooks insert custom logic at specific points in the build lifecycle.
    
    ```typescript
    hooks: {
      prePackage: async (config, platform, arch) => {
        // Run before @electron/packager -- generate assets, validate config
      },
      postMake: async (config, makeResults) => {
        // Run after all makers -- rename artifacts, upload to CDN, notify
        // Return modified makeResults array to affect subsequent steps
        return makeResults;
      },
    },
    ```
    
    | Hook                | When                            | Can Mutate?                           |
    | ------------------- | ------------------------------- | ------------------------------------- |
    | `generateAssets`    | Before start or package         | No                                    |
    | `prePackage`        | Before @electron/packager       | No                                    |
    | `packageAfterCopy`  | After packager copies build dir | No                                    |
    | `packageAfterPrune` | After devDependencies pruned    | No                                    |
    | `postPackage`       | After package completes         | No                                    |
    | `preMake`           | Before makers run               | No                                    |
    | `postMake`          | After makers complete           | Yes -- return modified `MakeResult[]` |
    | `readPackageJson`   | Every package.json read         | Yes -- return modified package.json   |
    
    See [examples/hooks.md](examples/hooks.md) for hook implementation examples.
    
    ---
    
    ### Pattern 7: Bundler Plugins (Vite / Webpack)
    
    Forge plugins integrate bundlers for compiling main and renderer process code with HMR.
    
    ```typescript
    import { VitePlugin } from "@electron-forge/plugin-vite";
    
    plugins: [
      new VitePlugin({
        build: [
          { entry: "src/main.ts", config: "vite.main.config.mts" },
          { entry: "src/preload.ts", config: "vite.preload.config.mts" },
        ],
        renderer: [
          { name: "main_window", config: "vite.renderer.config.mts" },
        ],
      }),
    ],
    ```
    
    **Status:** The Vite plugin is marked **experimental** as of v7.5.0 -- minor versions may include breaking changes.
    
    **Key detail:** The plugin injects global variables (`MAIN_WINDOW_VITE_DEV_SERVER_URL`, `MAIN_WINDOW_VITE_NAME`) for loading the renderer in dev vs production. Declare these in a `.d.ts` file for TypeScript.
    
    See [examples/core.md](examples/core.md) for Vite plugin setup and global variable declarations.
    
    </patterns>
    
    ---
    
    <decision_framework>
    
    ## Decision Framework
    
    ### Forge vs electron-builder
    
    ```
    Choosing a build tool?
    +-- Want first-party Electron support (ASAR integrity, universal macOS)?
    |   +-- YES --> Electron Forge (receives features same-day as Electron)
    +-- Need YAML-based config, NSIS installer, or broad community support?
    |   +-- YES --> electron-builder (more installer targets, larger community)
    +-- Need maximum customization for enterprise?
    |   +-- YES --> electron-builder (more config options, NSIS scripting)
    +-- Starting a new project?
        +-- YES --> Electron Forge (official recommendation, TypeScript config)
    ```
    
    | Factor                | Electron Forge              | electron-builder          |
    | --------------------- | --------------------------- | ------------------------- |
    | Maintainer            | Electron team               | Community                 |
    | Config format         | TypeScript / JavaScript     | YAML / JSON / JS          |
    | New Electron features | Same-day                    | Delayed                   |
    | Plugin ecosystem      | Makers, publishers, plugins | Built-in monolith         |
    | Windows installers    | Squirrel, WiX, MSIX, AppX   | NSIS, Squirrel, MSI, AppX |
    | macOS installers      | DMG, ZIP, PKG               | DMG, ZIP, PKG, MAS        |
    | npm downloads         | ~50K/week                   | ~1.4M/week                |
    | Architecture          | Composable packages         | Monolithic                |
    
    ### Maker Selection
    
    ```
    Which maker for your platform?
    +-- Windows?
    |   +-- Auto-updating desktop app --> Squirrel.Windows
    |   +-- Enterprise/IT deployment --> WiX MSI
    |   +-- Microsoft Store --> AppX or MSIX
    +-- macOS?
    |   +-- Direct distribution --> DMG (drag-to-install) + ZIP (for auto-updater)
    |   +-- Mac App Store --> PKG
    +-- Linux?
    |   +-- Debian/Ubuntu --> deb
    |   +-- Fedora/RHEL --> RPM
    |   +-- Universal sandboxed --> Flatpak or Snap
    ```
    
    </decision_framework>
    
    ---
    
    **Detailed resources:**
    
    - [examples/core.md](examples/core.md) -- forge.config.ts setup, makers, Vite plugin, fuses, dependency management
    - [examples/signing.md](examples/signing.md) -- macOS notarization, Windows Authenticode, Azure Trusted Signing, entitlements
    - [examples/publishers.md](examples/publishers.md) -- GitHub, S3, Snapcraft publishers with CI/CD patterns
    - [examples/hooks.md](examples/hooks.md) -- Build lifecycle hooks, custom makers, extending Forge
    - [reference.md](reference.md) -- Maker/publisher quick-reference tables, fuse options, CLI commands, Forge vs builder comparison
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    **Critical Issues:**
    
    - Placing `electron` in `dependencies` instead of `devDependencies` -- bloats the packaged app by ~200MB because Forge already provides the binary
    - Shipping without code signing -- macOS Gatekeeper blocks unsigned apps entirely; Windows SmartScreen shows scary warnings
    - Hardcoding signing credentials in `forge.config.ts` -- secrets end up in version control; always use `process.env`
    - Not enabling ASAR (`asar: false`) -- ships your source code as readable plain-text files
    - Not setting `RunAsNode: false` fuse -- allows `ELECTRON_RUN_AS_NODE=1` to execute arbitrary code with your app's permissions
    
    **Architecture Issues:**
    
    - Running `electron-forge make` on macOS expecting Windows .exe output -- makers run only on the target OS (use CI/CD with per-platform runners)
    - Placing native modules (better-sqlite3, sharp) inside ASAR without `asarUnpack` -- native addons cannot load from inside an ASAR archive
    - Not running `@electron/rebuild` for native modules -- modules compiled for system Node.js crash in Electron's Node.js runtime (Forge runs rebuild automatically during package, but manual installs need it)
    - Using `electron-forge package` for distribution -- this produces an uninstallable app bundle; use `make` for distributable installers
    
    **Configuration Mistakes:**
    
    - Setting `asar: true` without `asarUnpack` for native modules -- the app will crash at runtime trying to load the native addon
    - Forgetting the `platforms` array on makers -- maker runs on all platforms and fails on unsupported ones
    - Using `osxNotarize` without `osxSign` -- notarization requires a signed binary; Apple rejects unsigned submissions
    - Using your Apple ID password instead of an app-specific password for `osxNotarize` -- regular passwords are rejected when 2FA is enabled
    
    **Gotchas & Edge Cases:**
    
    - `electron-forge start` in dev mode does not run makers -- dev mode uses unpackaged source; always test with `make` before release
    - Notarization takes 2-10 minutes per build -- factor this into CI/CD timeout settings
    - Squirrel.Windows handles first-run events (shortcuts, desktop icons) -- your main process must handle Squirrel startup events or the app opens multiple times during install
    - `__dirname` resolves to virtual ASAR paths in packaged builds -- use `app.isPackaged` + `process.resourcesPath` for resource file paths
    - The Vite plugin is experimental since v7.5.0 -- minor version bumps may include breaking changes to its config shape
    - Azure Trusted Signing paths must not contain spaces -- signing fails silently if any path has spaces
    - Forge hooks run in parallel, not sequentially -- do not rely on execution order between hooks of the same type
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(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)**
    
    **Failure to follow these rules will produce insecure, bloated, or unsigned builds that OS security mechanisms will block or warn users about.**
    
    </critical_reminders>
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.