How heroic-games-launcher/heroicgameslauncher works
Purpose and Runtime
Heroic is a cross-platform desktop game launcher for Epic, GOG, and Amazon libraries, plus sideloaded applications. It is an Electron application: Node/Electron main process manages native capabilities and game tooling; React renders the desktop UI. Vite builds/dev-serves the renderer; electron-builder packages Linux, Windows, and macOS releases. Entry points: src/backend/main.ts, src/frontend/index.tsx, src/preload/index.ts, electron.vite.config.ts.
Process Boundary and IPC Contract
The renderer is intentionally separated from privileged Electron/Node APIs. The preload layer exposes a constrained API surface and relays calls/events through IPC; backend handlers perform filesystem, process, credential/store, and network operations. Shared IPC/domain types reduce cross-process drift. Paths: src/preload/ipc.ts, src/preload/api/index.ts, src/backend/ipc.ts, src/common/types/ipc.ts.
Desktop Lifecycle and Persistent State
The backend creates and controls the application window, tray integration, custom protocols, updates, logging, connectivity monitoring, and persisted Electron stores. Startup migrations preserve compatibility with prior stored configuration and launcher metadata. Paths: src/backend/main.ts, src/backend/main_window.ts, src/backend/electron_store.ts, src/backend/migration/index.ts.
Store-Manager Abstraction
Store-specific managers normalize authentication, users, libraries, game metadata, and lifecycle operations behind a central manager layer. Epic uses Legendary command wrappers; GOG uses gogdl-oriented modules; Amazon uses Nile. Sideloaded games enter the same library-oriented experience. Paths: src/backend/storeManagers/index.ts, src/backend/storeManagers/legendary/commands/index.ts, src/backend/storeManagers/gog/library.ts, src/backend/storeManagers/nile/library.ts.
Game Install, Launch, and Download Flow
UI library/game screens request install, import, update, move, uninstall, and launch through preload IPC. Backend store commands execute external tooling and report work through the download queue/progress events; frontend download and game views consume that state. Per-game configuration and overrides supply executable, environment, and launch settings. Paths: src/frontend/screens/Library/index.tsx, src/frontend/screens/Game/GamePage/index.tsx, src/backend/downloadmanager/downloadqueue.ts, src/backend/launcher.ts.
Compatibility Runtimes and Platform Integration
The backend selects/configures Wine, Proton, Crossover, umu, DXVK/DXMT, anti-cheat support, prefixes, and platform-specific process/filesystem behavior. It can download/manage Wine and Proton runtimes and integrates with Steam shortcuts. This is the boundary where game launch configuration becomes OS processes and external runner binaries. Paths: src/backend/wine/manager/ipc_handler.ts, src/backend/wine/runtimes/runtimes.ts, src/backend/utils/compatibility_layers.ts, src/backend/shortcuts/nonesteamgame/steamClient.ts.
Renderer Composition and State
React’s root composes screen-level workflows—login, library, game detail, downloads, settings, Wine management, console mode, and embedded store webviews—over global/context state. UI state invokes preload APIs rather than backend modules directly. Localization assets are bundled under public resources. Paths: src/frontend/App.tsx, src/frontend/state/ContextProvider.tsx, src/frontend/screens/Settings/index.tsx, public/locales/en/translation.json.
External Services and Delivery
External dependencies include Epic/Legendary, GOG/gogdl, Amazon/Nile, Wine/Proton release sources, Steam, SteamGridDB, compatibility/wiki sources (such as ProtonDB), and GitHub release APIs. Packaging targets native installers plus Flatpak; CI builds and releases per platform. Paths: src/backend/wiki_game_info/wiki_game_info.ts, src/backend/steamgrid/ipc_handler.ts, electron-builder.yml, flatpak/prepareFlatpak.js.
Main entry points: ipc.ts IPC handlers · App.tsx React app shell · index.ts Store manager layer · main.ts Electron main
Components 19
Renderer UI
React desktop interface and UI state.
- React app shell
src/frontend/App.tsx - Global UI state
src/frontend/state/ContextProvider.tsx - Library and game views · Library workflows and game-detail actions.
src/frontend/screens/Library/index.tsx - Settings and Wine UI
src/frontend/screens/Settings/index.tsx - Localization resources
public/locales/en/translation.json
Process Bridge
Constrained renderer-to-main API boundary.
- Preload API · Exposes the renderer's constrained privileged API.
src/preload/api/index.ts - IPC relay
src/preload/ipc.ts - Shared IPC types
src/common/types/ipc.ts
Electron Backend
Privileged lifecycle, game, and platform services.
- Electron main · Bootstraps privileged desktop services.
src/backend/main.ts - Window and persistent state · Window, tray, protocols, updates, stores, and migrations.
src/backend/main_window.ts - IPC handlers
src/backend/ipc.ts - Download queue · Runs game operations and emits progress.
src/backend/downloadmanager/downloadqueue.ts - Game launcher · Applies game settings and starts games.
src/backend/launcher.ts - Compatibility runtimes · Selects runners, prefixes, compatibility layers, and Steam shortcuts.
src/backend/wine/runtimes/runtimes.ts
Store Integrations
Normalized storefront and external game tooling.
- Store manager layer · Normalizes accounts, libraries, metadata, and lifecycle operations.
src/backend/storeManagers/index.ts - Epic via Legendary
src/backend/storeManagers/legendary/commands/index.ts - GOG and Amazon libraries · gogdl- and Nile-backed library access.
src/backend/storeManagers/gog/library.ts
Other components
- Vite / Electron build
electron.vite.config.ts
Connections 23
- Vite / Electron build → React app shell: builds renderer
- Vite / Electron build → Electron main: builds main process
- React app shell → Global UI state: uses
- React app shell → Library and game views: composes
- React app shell → Settings and Wine UI: composes
- React app shell → Localization resources: loads
- Library and game views → Preload API: requests game actions
- Settings and Wine UI → Preload API: configures runtimes
- Preload API → IPC relay: relays through
- IPC relay → IPC handlers: IPC calls and events
- Shared IPC types → IPC relay: defines contract
- Shared IPC types → IPC handlers: defines contract
- Electron main → Window and persistent state: controls
- Electron main → IPC handlers: registers
- IPC handlers → Store manager layer: library operations
- IPC handlers → Download queue: queues install and update
- IPC handlers → Game launcher: launches games
- IPC handlers → Compatibility runtimes: manages runners
- Store manager layer → Epic via Legendary: Epic operations
- Store manager layer → GOG and Amazon libraries: GOG and Amazon operations
- Download queue → Store manager layer: executes store work
- Game launcher → Compatibility runtimes: uses selected runtime
- Native and Flatpak packages → Vite / Electron build: packages build outputs