# electron/forge architecture

> Architecture diagram of the GitHub repository electron/forge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/electron/forge
- Repository: https://github.com/electron/forge

## Overview

##### Project Type and Purpose
- This is a monorepo for “Electron Forge,” an open-source CLI and toolkit that unifies build, packaging, templating, plugin, maker and publisher workflows for Electron apps. It exposes:
- A CLI front-end (packages/api/cli)
- A core API (packages/api/core)
- A rich plugin system (under packages/plugin)
- Maker modules (packages/maker) for various target formats (deb, dmg, zip, AppX, etc.)
- Publisher modules (packages/publisher) for different endpoints (GitHub, S3, GCS, etc.)
- Project templates (packages/template)
- Utility libraries (packages/utils)
- External integration code (packages/external)
- Tooling scripts (tools/)
- It’s written in TypeScript, orchestrated with Lerna/Nx, tested via Vitest, and CI’d on CircleCI/GitHub Actions.

##### File-Structure Analysis
- Top-level config: lerna.json, nx.json, tsconfig.base.json, CI pipelines (.circleci, .github/workflows).
- Monorepo packages/ grouped by domain:
- api/cli and api/core – command dispatch and core orchestration
- external – wrappers for third-party tools (e.g., create-electron-app)
- maker – build-output generators
- plugin – plug-in extension points for webpack, vite, natives unpacking, etc.
- publisher – deployment targets
- template – boilerplate app templates
- utils – shared helpers (core-utils, test-utils, tracer, types, logger)
- Tools/ holds documentation and code-generation scripts.
- Each package has its own src/, spec/ or test/ directories, package.json, README and often a Config.ts + main class.

##### Key Architecture Insights from the README
- Core goals: single-command start → CLI → core API → sequence of init|start|make|publish steps
- Under the hood it orchestrates Electron Rebuild, Electron Packager and user-supplied plugins/makers/publishers.
- Extensible plugin/maker/publisher pattern so users can drop in new modules.

##### Diagramming the Architecture
a. Main Components to Model
- CLI Front-End (packages/api/cli)
- Core Orchestrator (packages/api/core)
- Plugin System (packages/plugin/*)
- Maker Modules (packages/maker/*)
- Publisher Modules (packages/publisher/*)
- Template Engine (packages/template/*)
- Utilities (packages/utils/*)
- External Tools (packages/external/*)
- CI/CD Pipelines (CircleCI, GitHub Actions)
b. Relationships & Interactions
- User invokes CLI → CLI parses commands/options → passes control to Core API
- Core API loads Config → initializes plugins → calls:
– init (template generation)
– start (dev server, watchers)
– make (Electron Packager + makers)
– publish (publishers)
- Plugins intercept build steps via hook interface, alter webpack/vite configs or native unpacking
- Makers produce output artifacts (dmg, deb, zip, AppX…)
- Publishers upload artifacts (GitHub, S3, GCS, etc.)
- Utilities provide shared helper functions (file resolution, process spawning, logging)
- External modules (e.g., create-electron-app) are thin wrappers that call API/CLI internally
c. Architectural Patterns & Principles
- Modular monorepo managed with Lerna/Nx
- Plugin architecture (inversion-of-control via hook interfaces)
- Strategy pattern for makers/publishers/templates
- Separation of concerns: CLI vs Core vs Extension modules vs Utilities
- TypeScript + strong typing for Config and plugin contracts
d. Key Technologies & Frameworks
- Node.js + TypeScript
- Electron Packager & Electron Rebuild
- Lerna & Nx for monorepo orchestration
- Vitest for testing
- ESLint, Prettier, Husky for code quality
- CircleCI & GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        CLI["CLI Front-End\npackages/api/cli"]:::core
        Core["Core Orchestrator\npackages/api/core"]:::core
    end

    %% Extension Packages
    subgraph "Plugin System"
        BasePlugin["Base Plugin Interface\npackages/plugin/base"]:::extension
        AutoUnpack["Auto-Unpack Natives\npackages/plugin/auto-unpack-natives"]:::extension
        Electronegativity["Electronegativity Plugin\npackages/plugin/electronegativity"]:::extension
        Fuses["Fuses Plugin\npackages/plugin/fuses"]:::extension
        LocalElectron["Local Electron Plugin\npackages/plugin/local-electron"]:::extension
        VitePlugin["Vite Plugin\npackages/plugin/vite"]:::extension
        WebpackPlugin["Webpack Plugin\npackages/plugin/webpack"]:::extension
    end

    subgraph "Maker Modules"
        BaseMaker["Base Maker Interface\npackages/maker/base"]:::extension
        AppX["AppX Maker\npackages/maker/appx"]:::extension
        Deb["Debian Maker\npackages/maker/deb"]:::extension
        DMG["DMG Maker\npackages/maker/dmg"]:::extension
        Flatpak["Flatpak Maker\npackages/maker/flatpak"]:::extension
        PKG["Mac PKG Maker\npackages/maker/pkg"]:::extension
        RPM["RPM Maker\npackages/maker/rpm"]:::extension
        SnapMaker["Snap Maker\npackages/maker/snap"]:::extension
        Squirrel["Squirrel Maker\npackages/maker/squirrel"]:::extension
        Wix["Wix Maker\npackages/maker/wix"]:::extension
        ZipMaker["Zip Maker\npackages/maker/zip"]:::extension
    end

    subgraph "Publisher Modules"
        BasePub["Base Publisher Interface\npackages/publisher/base"]:::extension
        StaticPub["Static Publisher\npackages/publisher/base-static"]:::extension
        Bitbucket["Bitbucket Publisher\npackages/publisher/bitbucket"]:::extension
        ERSPub["Electron Release Server\npackages/publisher/electron-release-server"]:::extension
        GCSPub["Google Cloud Storage\npackages/publisher/gcs"]:::extension
        GitHubPub["GitHub Publisher\npackages/publisher/github"]:::extension
        Nucleus["Nucleus Publisher\npackages/publisher/nucleus"]:::extension
        S3Pub["S3 Publisher\npackages/publisher/s3"]:::extension
        Snapcraft["Snapcraft Publisher\npackages/publisher/snapcraft"]:::extension
    end

    subgraph "Template Engine"
        BaseTemplate["Base Template\npackages/template/base"]:::extension
        ViteTemplate["Vite Template\npackages/template/vite"]:::extension
        ViteTS["Vite TS Template\npackages/template/vite-typescript"]:::extension
        WebpackTS["Webpack TS Template\npackages/template/webpack-typescript"]:::extension
        WebpackTemplate["Webpack Template\npackages/template/webpack"]:::extension
    end

    subgraph "Utility Libraries"
        CoreUtils["Core Utilities\npackages/utils/core-utils"]:::util
        TestUtils["Test Utilities\npackages/utils/test-utils"]:::util
        Tracer["Tracer\npackages/utils/tracer"]:::util
        TypesDef["Types Definitions\npackages/utils/types"]:::util
        MultiLogger["Web Multi-Logger\npackages/utils/web-multi-logger"]:::util
    end

    subgraph "External Integration"
        CreateApp["Create Electron App Wrapper\npackages/external/create-electron-app"]:::external
    end

    subgraph "Tooling Scripts"
        Tools["Monorepo Tooling\ntools/"]:::external
    end

    subgraph "CI/CD Pipelines"
        CircleCI["CircleCI Config\n.circleci/config.yml"]:::ci
        GHActions["GitHub Actions\n.github/workflows/"]:::ci
    end

    %% Flow
    CLI -->|"invokes"| Core
    Core -->|"loads config & hooks"| BasePlugin
    Core --> AutoUnpack
    Core --> Electronegativity
    Core --> Fuses
    Core --> LocalElectron
    Core --> VitePlugin
    Core --> WebpackPlugin

    Core -->|"init"| BaseTemplate
    Core --> ViteTemplate
    Core --> ViteTS
    Core --> WebpackTS
    Core --> WebpackTemplate

    Core -->|"make"| BaseMaker
    Core --> AppX
    Core --> Deb
    Core --> DMG
    Core --> Flatpak
    Core --> PKG
    Core --> RPM
    Core --> SnapMaker
    Core --> Squirrel
    Core --> Wix
    Core --> ZipMaker

    Core -->|"publish"| BasePub
    Core --> StaticPub
    Core --> Bitbucket
    Core --> ERSPub
    Core --> GCSPub
    Core --> GitHubPub
    Core --> Nucleus
    Core --> S3Pub
    Core --> Snapcraft

    Core -->|"uses"| CoreUtils
    Core --> TestUtils
    Core --> Tracer
    Core --> TypesDef
    Core --> MultiLogger

    CreateApp -->|"wraps"| CLI
    CreateApp --> Core

    Tools -->|"scripts run by"| CircleCI
    Tools --> GHActions
    CircleCI --> Tools
    GHActions --> Tools

    %% Click Events
    click CLI "https://github.com/electron/forge/tree/main/packages/api/cli"
    click Core "https://github.com/electron/forge/tree/main/packages/api/core"
    click BasePlugin "https://github.com/electron/forge/tree/main/packages/plugin/base"
    click AutoUnpack "https://github.com/electron/forge/tree/main/packages/plugin/auto-unpack-natives"
    click Electronegativity "https://github.com/electron/forge/tree/main/packages/plugin/electronegativity"
    click Fuses "https://github.com/electron/forge/tree/main/packages/plugin/fuses"
    click LocalElectron "https://github.com/electron/forge/tree/main/packages/plugin/local-electron"
    click VitePlugin "https://github.com/electron/forge/tree/main/packages/plugin/vite"
    click WebpackPlugin "https://github.com/electron/forge/tree/main/packages/plugin/webpack"
    click BaseMaker "https://github.com/electron/forge/tree/main/packages/maker/base"
    click AppX "https://github.com/electron/forge/tree/main/packages/maker/appx"
    click Deb "https://github.com/electron/forge/tree/main/packages/maker/deb"
    click DMG "https://github.com/electron/forge/tree/main/packages/maker/dmg"
    click Flatpak "https://github.com/electron/forge/tree/main/packages/maker/flatpak"
    click PKG "https://github.com/electron/forge/tree/main/packages/maker/pkg"
    click RPM "https://github.com/electron/forge/tree/main/packages/maker/rpm"
    click SnapMaker "https://github.com/electron/forge/tree/main/packages/maker/snap"
    click Squirrel "https://github.com/electron/forge/tree/main/packages/maker/squirrel"
    click Wix "https://github.com/electron/forge/tree/main/packages/maker/wix"
    click ZipMaker "https://github.com/electron/forge/tree/main/packages/maker/zip"
    click BasePub "https://github.com/electron/forge/tree/main/packages/publisher/base"
    click StaticPub "https://github.com/electron/forge/tree/main/packages/publisher/base-static"
    click Bitbucket "https://github.com/electron/forge/tree/main/packages/publisher/bitbucket"
    click ERSPub "https://github.com/electron/forge/tree/main/packages/publisher/electron-release-server"
    click GCSPub "https://github.com/electron/forge/tree/main/packages/publisher/gcs"
    click GitHubPub "https://github.com/electron/forge/tree/main/packages/publisher/github"
    click Nucleus "https://github.com/electron/forge/tree/main/packages/publisher/nucleus"
    click S3Pub "https://github.com/electron/forge/tree/main/packages/publisher/s3"
    click Snapcraft "https://github.com/electron/forge/tree/main/packages/publisher/snapcraft"
    click BaseTemplate "https://github.com/electron/forge/tree/main/packages/template/base"
    click ViteTemplate "https://github.com/electron/forge/tree/main/packages/template/vite"
    click ViteTS "https://github.com/electron/forge/tree/main/packages/template/vite-typescript"
    click WebpackTS "https://github.com/electron/forge/tree/main/packages/template/webpack-typescript"
    click WebpackTemplate "https://github.com/electron/forge/tree/main/packages/template/webpack"
    click CoreUtils "https://github.com/electron/forge/tree/main/packages/utils/core-utils"
    click TestUtils "https://github.com/electron/forge/tree/main/packages/utils/test-utils"
    click Tracer "https://github.com/electron/forge/tree/main/packages/utils/tracer"
    click TypesDef "https://github.com/electron/forge/tree/main/packages/utils/types"
    click MultiLogger "https://github.com/electron/forge/tree/main/packages/utils/web-multi-logger"
    click CreateApp "https://github.com/electron/forge/tree/main/packages/external/create-electron-app"
    click Tools "https://github.com/electron/forge/tree/main/tools/"
    click CircleCI "https://github.com/electron/forge/blob/main/.circleci/config.yml"
    click GHActions "https://github.com/electron/forge/tree/main/.github/workflows/"

    %% Styles
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px
    classDef extension fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef util fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef ci fill:#D3D3D3,stroke:#333,stroke-width:1px
```
