HeroicGamesLauncher Documentation

A games launcher for GOG, Amazon and Epic Games for Linux, Windows and macOS.

11,639 stars TypeScript TypeScript 1 file · ~6,416 tokens #amazon-prime#electron#epic-games-launcher#epic-games-store#epic-store#gaming#gog#gog-galaxy
RAW Doc

File: README.md

Heroic Games Launcher








Heroic is an Open Source Game Launcher for Linux, Windows and macOS.
Right now it supports launching games from the Epic Games Store using Legendary, GOG Games using our custom implementation with gogdl and Amazon Games using Nile.

Heroic is built with Web Technologies:







Index

Features available right now

  • Login with an existing Epic Games, GOG or Amazon account
  • Install, uninstall, update, repair and move Games
  • Import an already installed game
  • Play Epic games online [AntiCheat on macOS and on Linux depends on the game]
  • Play games using Wine or Proton [Linux]
  • Play games using Crossover [macOS]
  • Download custom Wine and Proton versions [Linux]
  • Access to Epic, GOG and Amazon Games stores directly from Heroic
  • Search for the game on ProtonDB for compatibility information [Linux]
  • Show ProtonDB and Steam Deck compatibility information [Linux]
  • Sync installed games with an existing Epic Games Store installation
  • Sync saves with the cloud
  • Custom Theming Support
  • Download queue
  • Add Games and Applications outside GOG, Epic Games and Amazon Games
  • Define your categories to organize your collection

Planned features

  • Support Other Store (IndieGala, etc)

Supported Operating Systems

  • Linux:
    • Ubuntu (latest 2 LTS versions)
    • Fedora (latest 2 versions)
    • Arch Linux & derivatives (Manjaro, Garuda, EndeavourOS)
    • Heroic will still work on most distros, but it is up to you to get it to work
      Chances are though that someone on our Discord can help you
  • SteamOS (downloading using Discover only)
  • Windows 10 & 11
  • macOS 14 or newer

Language Support

Expand

Thanks to the community, Heroic was translated to almost 40 different languages so far:

  • English
  • Azerbaijani
  • Basque
  • Belarussian
  • Bosnian
  • Bulgarian
  • Catalan
  • Czech
  • Croatian
  • Simplified Chinese
  • Traditional Chinese
  • Dutch
  • Estonian
  • Finnish
  • French
  • German
  • Greek
  • Hebraic
  • Japanese
  • Korean
  • Hungarian
  • Italian
  • Indonesian
  • Malayalam
  • Norwegian Bokmål
  • Persian
  • Polish
  • Portuguese
  • Portuguese (Brazil)
  • Romanian
  • Russian
  • Serbian
  • Spanish
  • Slovak
  • Swedish
  • Tamil
  • Turkish
  • Ukrainian
  • Vietnamese

Help with Translations [Here](https://hosted.weblate.org/projects/heroic-games-launcher)

Installation

Linux

Flatpak

Heroic is available on Flathub, so you should be able to easily install it on most distros with Software Centers (Pop!_Shop, Discover, etc.)

Distribution-specific instructions

If you're not using the Flatpak version, keep GE-Proton as your Wine runner. With umu enabled by default, no additional Wine dependencies are required.

Debian, Ubuntu and Derivatives

Download the file ending in .deb from the latest release.
Double-click it to open it up in your Software Manager, or run sudo dpkg -i Heroic*amd64.deb to install it directly.

Arch (AUR)

We currently only support one AUR package: heroic-games-launcher-bin. Although you might find other packages there, do not ask support for them on this GitHub or on our Discord, ask their maintainers directly.


  • (stable release, recommended)

Please see the Arch Wiki on how to install them

Fedora

You can download the file ending in .rpm from the latest release and install it with sudo dnf install ./heroic-*.x86_64.rpm.

Alternatively, you can use the Flatpak package.

Nix(OS)

Two community-maintained versions are available in nixpkgs, named heroic (with an FHS environment) and heroic-unwrapped (without FHS).

  • Nix shell: nix-shell -p heroic

  • NixOS:

    nixos
    # /etc/nixos/configuration.nix
{ config, pkgs, ... }:

{
  users.users.example = {
    isNormalUser = true;
    description = "Example user";
    packages = with pkgs; [
      heroic
    ];
  };
}

Other Distributions (AppImage and TAR.XZ)

Since these two distribution formats don't have a form of dependency management, make sure the curl command is available. You might run into weird issues if it's not.

AppImage

  • Download the file ending in .AppImage from the latest release
  • Make it executable (chmod +x Heroic*.AppImage)
  • Run it (double-click in most file managers, or run ./Heroic*.AppImage)

.tar.xz

  • Download the file ending in .tar.xz from the latest release
  • Extract it anywhere
  • Run the heroic file in the folder you extracted it to (double-click in most file managers, or run ./heroic)

Windows

WinGet

If you use WinGet (installed by default on Windows 11 and modern versions of 10), you can run winget install Heroic in a terminal to install Heroic.

Manual installl

Download the Heroic Installer (Heroic-x.x.x-Setup.exe) or the portable version (Heroic-x.x.x-Portable.exe) from the latest release. Run the executable you downloaded to install/run Heroic.
The Setup will create shortcuts to Heroic on your Desktop and in your Start Menu.

macOS

If you use Homebrew, you can run brew install --cask --no-quarantine heroic to install Heroic.
Otherwise, download the file ending in .dmg from the latest release, double-click it to mount it, and drag the "Heroic" application into the "Applications" folder.

Development environment

This part will walk you through setting up a development environment so you can build Heroic binaries yourself or make changes to the code.

  1. Make sure Git, NodeJS, and pnpm 10 are installed
    NOTE: On Windows, due to an issue with electron-builder, you'll need the standalone version of pnpm (@pnpm/exe)
    to build packages

  2. Clone the repo and enter the cloned folder, for example with these commands:

    bash
    git clone https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher.git --recurse-submodules
cd HeroicGamesLauncher

  3. Make sure all dependencies are installed by running pnpm install

  4. Download all helper binaries using pnpm download-helper-binaries

Building Heroic Binaries

Run the appropriate command for your OS:

  • Build for Linux:

    bash
    pnpm dist:linux # Optionally specify a package to create (eg: deb, pacman, tar.xz, rpm, AppImage); default: AppImage

  • Build for Windows:

    bash
    pnpm dist:win

  • Build for Mac:

    bash
    pnpm dist:mac

Building with VS Code

Instead of using the above commands to build Heroic, you can also use the Tasks in VSCode to build.
To do that, open up the command palette (Ctrl + P), type in "task" and press Space. You will then see 3 build tasks, "Build for Linux", "Build for Windows", and "Build for MacOS". Click the one you want to run.

Quickly testing/debugging Heroic on your own system

If you want to quickly test a change, or you're implementing features that require a lot of restarts, you can use Vite's development server to speed up the process:
Go to the "Run and Debug" tab of VSCode and start the "Launch Heroic (HMR & HR)" task (alternatively, if you're not using VSCode or just prefer the terminal, run pnpm start). Heroic will start up after a short while, and once you make any change to the code, it'll reload/restart.

Development on Nix

After cloning the repository, Nix users can use nix-shell to make Node.JS/pnpm available and automatically run installation step 3 and 4. See shell.nix for more information.

Sponsors

Thanks Weblate for hosting our translations

Thanks Signpath for providing free signing of Windows binaries

Screenshots

Expand

Credits

Weblate: Localization platform

Those Awesome Guys: Gamepad prompts images

Tools We Use to Run Games

Heroic would not be possible without the work done in many other projects:

So be sure to follow and support those projects too!

File: doc/cla.md

HEROIC GAMES LAUNCHER

CONTRIBUTION LICENSE AGREEMENT

This Contribution License Agreement (the “CLA”) is between the individual set forth in the signature block (“You”) and Heroic Labs, Inc. (“Heroic”), effective as of the date of Your signature and sets forth the terms pursuant to which You may provide Contributions to Heroic.
You accept and agree to the following terms and conditions for Your past, present and future Contributions submitted to Heroic’s Heroic Games Launcher project (the “Project”). In return, Heroic will not use Your Contributions in a way that is contrary to Heroic’s business objectives. Except for the license granted herein to Heroic and recipients of software distributed by Heroic, You reserve all right, title, and interest in and to Your Contributions.

  1. Definitions. “Contribution” means any original work of authorship, including any modifications or additions to an existing work, that You intentionally submit, or have submitted previously, to Heroic for inclusion in, or documentation of, the Project. “Submit” means any form of electronic, verbal, or written communication sent to Heroic or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, Heroic for the purpose of discussing and improving the Project, but excluding communication that is conspicuously marked or otherwise designated in writing by You as “Not a Contribution.”

  2. Copyright License. Subject to the terms and conditions of this CLA, You hereby grant to Heroic and to recipients of software distributed by Heroic a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.

  3. Patent License. Subject to the terms and conditions of this CLA, You hereby grant to Heroic and to recipients of software distributed by Heroic a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Project, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Project to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that Your Contribution, or the Project to which You have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this CLA for that Contribution or Project will terminate as of the date such litigation is filed.

  4. Representations and Warranties. You represent and warrant to Heroic that:

    a. You are legally entitled to grant the above license, and if Your employer(s) has rights to intellectual property that You create that includes Your Contributions, then You represent and warrant that You have received permission to make Contributions on behalf of that employer, that Your employer has waived such rights for Your Contributions to Heroic, or that Your employer has executed a separate CLA with Heroic;

    b. Each of Your Contributions is Your original creation (see section 6 for submissions on behalf of others); and

    c. Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which You are personally aware and which are associated with any part of Your Contributions.

  5. Support; Disclaimer. You are not expected to provide support for Your Contributions, except to the extent You desire to do so. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.

  6. Third Party Works. If You wish to submit work that is not Your original creation, then You may submit it to Heroic separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which You are personally aware, and conspicuously marking the work as “Submitted on behalf of a third-party: [named here]”.

  7. Notice. You agree to notify Heroic of any facts or circumstances of which You become aware that would make Your representations in this CLA inaccurate in any respect.

  8. General. This CLA is the entire understanding and agreement with respect to the subject matter hereof, and supersedes any and all prior or contemporaneous representations, understandings, and agreements, between the parties regarding same. If any part of this CLA is found to be unenforceable, the remaining portions of this CLA will remain in full force and effect. No modification of or amendment to this CLA, nor any waiver of any rights under this CLA, will be effective unless in writing signed by the party to be charged, and the waiver of any breach or default will not constitute a waiver of any other right under this CLA or any subsequent breach or default. Nothing in this CLA creates and the parties do not intend to create, any partnership or joint venture between themselves. Either party may freely assign this CLA. This CLA is binding upon and will inure to the benefit of a party’s successors and permitted assigns. This CLA will be governed by the laws of the State of Delaware. Exclusive jurisdiction of any and all disputes hereunder will be in the state and federal courts in Wilmington, Delaware. This CLA may be executed in counterparts with the same effect as if all signatories had signed the same document.

File: doc/electron_store.md

Similar to our IPC system, we also type-check our Electron Stores. If you want to use its functionality in your code, remember:

  • Use TypeCheckedStoreBackend and TypeCheckedStoreFrontend
  • Modifying our list of stores (adding new ones, changing the structure) can be done in src/common/types/electron_store.ts
    Note that you'll have to be very careful when changing an existing store's structure, as the old structure does not get converted to
    your new format automatically (to facilitate this, you can use migrations)
  • When accessing elements, use <store>.get with a default value, or <store>.get_nodefault if you can't/don't want to
    provide a default

Specific store structure notes:

  • If you have a store with pre-set keys, you can just add those keys into the interface:
    ts
    interface StoreStructure {
  // ...
  myStoreName: {
    myKey: boolean /* or any other type here */
  }
}
  • If your store's keys are set dynamically (for example, a store that uses AppNames as keys), you can use
    Index Signatures instead:
    ts
    interface StoreStructure {
  // ...
  myStoreName: {
    [key: string]: boolean /* or any other type here */
  }
}

File: doc/frontend_design_system.md

Frotend Design System

Type System

the type system is adjustable with two variables. Like you've seen, font-size sets the medium font size (1rem) and --text-scale-ratio adjusts the difference between text size steps. By keeping these as variables instead of hardcoding all the --text- values in rem units, we ensure that each step is exactly 20% (if --text-scale-ratio equals 1.2) different from the next step. This ensures visual consistency and gives options uniformly along the range of text sizes we want to support. This makes it easy to iterate, add breakpoints, and prevents the situation where one font size is updated but the others are not whether that be in a breakpoint or in the _typography.scss file. It also isn't much of a limitation at all on the design side of things.

Spacing System

Relative Spacing

the spacing system is first specified in em units. This means that it is a multiple of that element's font size. So let's say you have h6 at 1 rem (16px) and want margin-bottom to be 50% of this font size. By setting margin-bottom = 0.5 em (--space-xs) on the element, you accomplish this. When someone introduces a breakpoint later and changes the font, the margin-bottom won't have to be updated because it's specified in em. (So you probably won't have to update these css vars in media query breakpoints.) By creating css variables for these sizes, we constrain the components to use one of these predefined sizes, which again enforces visual consistency and makes the code much more maintainable. Designers can now iterate on the entire app's margins and paddings by tweaking these values.

Fixed Spacing

The fixed spacing system is intended for margins and paddings that shouldn't change based on the font size of the element. So if you want something to truly be 4px instead of 25% of a 1rem, use this.

FAQ

How do I pick the spacing values?

Ideally there is a figma file that has already designed the component. If not, it will be up to the frontend dev to select a font size or spacing value.

How should I handle border-radius?

If you want it to adjust dynamically to font size changes in the element (e.g. when hitting a breakpoint), use --space-X. If you want a constant value in px, use --space-X-fixed.

Why should I use a spacing value instead of a text value?

It's important that we keep our design system parameterized and defined in one place for maintainability and ease of iteration by our designers.

I can't find the px value I want. Can I hardcode it?

This isn't good practice. It's important to keep our text sizes, margins, and paddings constrained to a small number of choices so that we can provide a visual consistent user experience.

If you truly need a different value, consider changing the --space or --space fixed category value defined in _spacing.scss. Consult the designers first though.

File: doc/frontend_testing.md

Overview of Frontend testing enviroment

Configuration files

The frontend test's are running via jest.
The related config can be found under src/jest.config.js

Jest using ts-jest to test .tsx and .ts files and is configured
with the tsconfig.js from the root path.

Mocks

All the global mocks can be found under src/test_helpers/mock and are
invoked if you import the following patterns in your frontend file:

  • *.css files
    • ignoring *.css imports in the test
  • electron
    • mocking all ipcRenderer calls with jest-when plugin, which are invoked in the frontend source files.
    • provides a function to init all electron mocks.
      • this function is mostly called from other helper functions and shouldn't be needed that often.
  • react-i18next
    • mocks the useTranslation hook and the t function

Note1: If you implement new ipcRenderer calls in the frontend, make sure they are resolved correctly in the src/test_helpers/mock/electron.ts file, else some test's can run in unresolved promises and fail.

Note2: If new mocks are needed globally add them to the field moduleNameMapper in the src/jest.config.js.

Pre defined type configurations

In the file src/test_helpers/testTypes.ts are alot of predefined
type configurations which can be used to provide configurations for the
test's and also to manipulate them easy for your needs.

All this type configurations are defined via a template class TestType<Type>. This provides the function set(), get() and reset().

Also there is a helper function resetTestTypes() which resets all type
configurations to there default values. It is a good practice to call this in a beforeEach() of a describe entry.

File: doc/ipc.md

To add type safety to Electron's IPC system, we've made the following changes to what you'd usually see in an Electron app:

  • Since contextIsolation is turned on, you cannot simply use ipcRenderer.send/ipcRenderer.invoke in the frontend to make IPC calls to the backend. Instead, we define a helper function for each IPC channel in src/backend/api/, which will be injected into the frontend on load. It'll then be available as window.api.yourFunction. See Context Isolation for more details
  • To make sure that the parameters passed to & value returned from the callback of an ipcMain.on/ipcMain.handle call are correct, every IPC channel has to be defined in src/common/typedefs/ipcBridge.d.ts (adding new channels either to SyncIPCFunctions or AsyncIPCFunctions). This will also result in your callback's parameters automatically getting type annotations, and your helper function in src/backend/api/ getting type-checked as well

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#amazon-prime Browse amazon-prime catalog → #electron Browse electron catalog → #epic-games-launcher Browse epic-games-launcher catalog → #epic-games-store Browse epic-games-store catalog → #epic-store Browse epic-store catalog → #gaming Browse gaming catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →