Onyx - Premium Unified Game Library

A modern Electron application built with React, TypeScript, Vite, and Tailwind CSS. Onyx provides a unified interface for managing games from multiple launchers (Steam, Epic, GOG, Xbox, and more).

• Download: https://onyxlauncher.co.uk/ · GitHub Releases — Windows installer, plus AppImage / .deb / .rpm for Linux
• Free and open source — GPL-3.0-or-later license · Changelog / What's new

Platform Support

Windows is the primary, fully supported platform.

Linux support is in testing as of 0.16.0. What works, and what does not:

	Windows	Linux
Steam	Yes	Yes — native, Flatpak and Snap installs
Epic	Yes — Epic Games Launcher	Yes — via Heroic
GOG	Yes — GOG Galaxy	Yes — via Heroic, or a ~/GOG Games folder scan
Lutris / Bottles	—	Detected; games found by folder scan
itch.io	Yes	Yes
Xbox Game Pass, EA App, Ubisoft Connect, Battle.net, Humble, Rockstar	Yes	No Linux client exists — these sources are hidden on Linux
Suspend / Resume	Disabled by default	Not supported

Notes for Linux:

• Games installed through Heroic are launched through Heroic, so each one keeps the Wine/Proton configuration you gave it. Onyx does not run the game binary directly.
• Native Linux games are detected by extension (.x86_64, .sh, AppImage) or by the executable bit. Windows games in a Steam or Heroic library are also listed, since those run under Proton/Wine.
• Only the AppImage receives in-app updates. .deb and .rpm installs update through your distribution's package manager.
• Expect rough edges — please open an issue for anything you hit.

macOS is not supported and is not currently planned.

Screenshots

Grid View	List View
Logo View	Carousel View

All four view types: Grid, List, Logo, and Carousel. See the website for more.

Build Channels

Onyx supports three separate build channels that can coexist on the same computer:

• Development: Local development builds (localhost)
• Alpha: Testing builds from the develop branch (installs as "Onyx Alpha" with yellow icon)
• Production: Stable builds from the main branch (installs as "Onyx")

Alpha and Production builds use different App IDs, allowing them to be installed side-by-side without conflicts. Alpha builds display a yellow "ALPHA" banner in the top-right corner for easy identification.

Git Workflow

All local development and testing is done on the master branch.

Pushing Alpha Builds

When ready to deploy an alpha build:

git push origin master:develop --force

This overwrites the develop branch with master, triggering an automatic Alpha build via GitHub Actions.

Pushing Production Builds

Once the alpha build is tested and confirmed working:

git push origin develop:main --force

This overwrites the main branch with develop, triggering an automatic Production build via GitHub Actions.

Project Structure

├── main/              # Electron main process (backend)
│   ├── main.ts        # Main process entry point
│   ├── preload.ts     # Preload script with ContextBridge
│   └── tsconfig.json  # TypeScript config for main process
├── renderer/          # React frontend
│   ├── src/
│   │   ├── App.tsx    # Main React component
│   │   ├── main.tsx   # React entry point
│   │   └── index.css  # Tailwind CSS imports
│   └── index.html     # HTML template
├── dist-electron/     # Compiled main process files
└── dist/              # Built renderer files (after build)

Features

• ⚡ Vite for fast development and building
• ⚛️ React 18 with TypeScript
• 🎨 Tailwind CSS for styling
• 🔒 Secure IPC communication via ContextBridge
• 🌙 Dark-themed UI
• 📦 TypeScript for type safety

Development

1. Install dependencies:

   npm ci

2. Set up API credentials (optional, for game metadata and artwork):

   • Copy .env.example to .env
   • Add keys for the services you want (IGDB, RAWG, SteamGridDB). See .env.example and the Third-party services (APIs) section below.
   • Example (IGDB only): get credentials from the Twitch Developer Console (use http://localhost:5173 as the OAuth Redirect URL) and add IGDB_CLIENT_ID and IGDB_CLIENT_SECRET to .env.

   IGDB_CLIENT_ID=your_client_id_here
   IGDB_CLIENT_SECRET=your_client_secret_here

   Security note: Do NOT commit real API credentials to source control. If credentials are ever committed, rotate them immediately and follow incident response procedures.

   Credential storage: Onyx now stores API credentials in the OS secure credential store (Windows Credential Locker, macOS Keychain, or the system secret service) when available. If the OS secure store isn't available, it will temporarily fall back to electron-store (not recommended).

3. Build the main process:

   npx tsc -p main/tsconfig.json

4. Run in development mode:

   npm run electron:dev

   This will:

   • Start the Vite dev server on http://localhost:5173
   • Launch Electron when the server is ready
   • Open DevTools automatically

Third-party services (APIs)

Onyx uses the following third-party services for game metadata and artwork. You must obtain your own API keys and comply with each service's terms of use and rate limits.

Service	Purpose	Configure in app (Settings > APIs) or via env (see .env.example)
IGDB	Game metadata	IGDB_CLIENT_ID, IGDB_CLIENT_SECRET
RAWG	Game metadata	RAWG_API_KEY
SteamGridDB	Artwork (covers, logos, etc.)	STEAMGRIDDB_API_KEY
GiantBomb	Game metadata + artwork	GIANTBOMB_API_KEY (currently unavailable while API platform is being rebuilt)

Do not commit real API credentials to the repository. Keys can be set in the app's Settings > APIs or via environment variables when running the app.

Building

Development Build

To build for local development:

npm run build

This compiles both the main process and the renderer, then you can run:

npm run electron:build

Production Builds

The project supports multiple build channels:

Alpha Build (for testing):

npm run build:alpha

• Creates "Onyx Alpha" with App ID: com.lasikiewicz.onyx.alpha
• Includes yellow "ALPHA" banner in the UI
• Outputs installer and artifacts to release/

Production Build:

npm run build:prod

• Creates "Onyx" with App ID: com.lasikiewicz.onyx
• Standard production build
• Outputs installer and artifacts to release/

Standard Distribution Build:

npm run dist

• Uses default production settings
• Automatically increments build version
• Generates and validates icons

Linux Builds (run on Linux; rpmbuild and fakeroot must be installed for the .rpm/.deb targets):

npm run build:linux

• Produces an AppImage, a .deb and an .rpm in release/
• npm run build:linux:alpha builds the Alpha profile instead
• LINUX_MAINTAINER="Name <email>" overrides the maintainer embedded in the .deb/.rpm metadata

Automated Builds via GitHub Actions

The project includes automated builds via GitHub Actions:

• Pushing to develop branch: Automatically builds Alpha version and creates a pre-release on GitHub
• Pushing to main branch: Automatically builds Production version and creates a stable release on GitHub

Each release carries a Windows installer plus Linux packages. These are built by two separate jobs: a Windows job that owns the tag, the release and its notes, and a Linux job that attaches its AppImage, .deb, .rpm and latest-linux.yml to that same release. The Linux job runs needs: build, so a Linux packaging failure can never stop the Windows installer from publishing.

Releases are tagged as:

• Alpha: alpha-v{version} (marked as pre-release)
• Production: v{version} (stable release)

If a push does not start a run — GitHub throttles webhook delivery during Actions incidents, which drops the event silently — trigger the build manually instead of making an empty commit:

gh workflow run build.yml --ref main

Workflow:

1. Work and test locally on master branch
2. Force push master to develop for Alpha builds: git push origin master:develop --force
3. Test the Alpha build
4. Force push develop to main for Production builds: git push origin develop:main --force
5. Download releases from the GitHub Releases page

For maintainers: "Push to git" or "push to git master" means approval to push current changes to master after summarizing; do not push without explicit permission.

Icon Management

The project includes automatic icon validation to ensure icons always work correctly:

• Icons are automatically validated before builds
• Icons are automatically generated before distribution builds
• Icons are validated in CI/CD to prevent broken builds

To manually validate icons:

npm run validate-icons

To regenerate icons from the source SVG:

npm run generate-icons

See docs/ICON_REQUIREMENTS.md for detailed icon requirements and troubleshooting.

Scripts

Development

• npm run dev - Start Vite dev server only
• npm run build - Build both main and renderer (validates icons automatically)
• npm run electron:dev - Run in development mode
• npm run electron:build - Run built application
• npm run electron - Run Electron (requires built files)

Production Builds

• npm run build:alpha - Build Alpha version (Onyx Alpha)
• npm run build:prod - Build Production version (Onyx)
• npm run dist - Build distribution package (generates and validates icons automatically)

Icons

• npm run generate-icons - Generate all icon formats from resources/icon.svg via scripts/generate-icons.mjs
• npm run validate-icons - Validate that all required icon files exist and are valid

Checks (run before submitting PRs)

• npm run lint - Run the project ESLint checks for React hooks, duplicate imports, and common TypeScript hygiene issues
• npm run scan:secrets - Scan for committed secrets; must pass (see scripts/secret-scan.js)
• npm run check:no-raw-ipc - Enforce no raw window.ipcRenderer in renderer (see scripts/check-no-raw-ipc.js)
• npm run docs:sync - Auto-update generated documentation blocks in .agent/docs/
• npm run docs:check - Ensure required docs are updated for staged code changes

Contributor docs guard (structure-first)

Before editing code, check .agent/docs/structure.md to identify which documentation file owns the area you are changing.

• If you change mapped files, update the mapped docs in the same commit.
• If architecture, data flow, IPC contracts, or build/release flow changes, update .agent/docs/architecture.md.
• Mapping source of truth is .agent/docs/doc-map.json.
• Pre-commit and CI enforce this automatically via docs:sync and docs:check.

Maintainer scripts (GitHub API)

Scripts that call the GitHub API (e.g. create-pr.js, create-pr-credentials.js, list-runs.js, post-pr-comment.js, fetch-failing-jobs.js) are for maintainers of the canonical repo. They read:

• GHTOKEN (required) — GitHub token with appropriate scopes (e.g. repo, workflow).
• GITHUB_REPOSITORY (optional) — owner/repo; default Lasikiewicz/onyx. Set this when running against a fork (e.g. youruser/onyx).
• GITHUB_ISSUE_NUMBER (optional) — Used by post-pr-comment.js only; default 3.

Do not put tokens in .env or commit them; set them in your shell (e.g. $env:GHTOKEN = 'ghp_xxx' in PowerShell). See .github/CONTRIBUTING.md for more.

Disabled Features (Security)

The project contains a few features that are implemented but intentionally disabled until reviewed and validated:

• Suspend/Resume Feature — Implemented in main/ProcessSuspendService.ts, but disabled by default due to potential system-level side effects and admin requirements. See docs/SUSPEND_FEATURE_QUICK_REFERENCE.md for details.
• Steam Playtime Sync — Playtime synchronization and display logic exists but is disabled by default. See docs/STEAM_PLAYTIME_QUICK_REFERENCE.md for details.

These features are gated behind explicit enablement steps and require additional testing and documentation before being turned on in production.

IPC Communication

The app uses ContextBridge for secure IPC communication. The preload script exposes safe APIs to the renderer process. You can extend main/preload.ts to add more IPC channels as needed.

Window Configuration

• Default Size: 1920x1080 pixels
• Resizable: Yes
• Minimum size: 1280x720 pixels
• Theme: Dark background with gradient
• Title: Dynamically set based on build channel ("Onyx" or "Onyx Alpha")

Build Configuration

The build configuration is managed in electron-builder.config.js, which supports dynamic configuration based on the BUILD_PROFILE environment variable:

• BUILD_PROFILE=alpha - Configures for Alpha builds
• BUILD_PROFILE=production - Configures for Production builds (default)

The configuration automatically adjusts:

• App ID (for side-by-side installation)
• Product Name (window title and installer name)
• Icon paths
• GitHub release settings

Community

• Main website: https://onyxlauncher.co.uk/
• Discord and Ko-fi links in the app and on the website point to the official Onyx project. If you fork the repository and publish your own builds, you can replace these links in the app (e.g. in Settings) and in the website/ source.

Contributing and community docs

• .github/CONTRIBUTING.md — How to run the app, get API keys, and submit PRs (including required checks).
• .github/CODE_OF_CONDUCT.md — Community standards and enforcement.
• .github/SECURITY.md — How to report security vulnerabilities (do not open public issues for security-sensitive bugs).

License

GPL-3.0-or-later — see LICENSE for the full text.