itch

itch is the desktop application for playing games from itch.io. Its stated goal is to let users download and run games, receive update notifications, and keep games updated, without replacing the itch.io website itself. Architecture The app is an Electron application with a multi-process design. The main process (Node.js) handles state management with Redux, business logic, and coordination with companion components; it uses a "reactor" pattern for side effects from Redux actions. The renderer process is a React-based UI whose state is synchronized from the main process via electron-redux. Two companion Go components support it: - butler: a daemon that handles downloads, installs, updates and launching of games, keeps a SQLite database of installation data, and communicates with the app over TCP-based RPC. It is spawned as a child process tied to the app's lifecycle. - itch-setup: an executable that handles initial installation on all platforms and manages self-update checks and restarts. Version management (broth) The app manages butler and itch-setup versions through a system called broth, a service that proxies the itch.io API to provide fixed download URLs for binaries and assets. Binaries are hosted under broth.itch.zone with platform identifiers such as linux-amd64, darwin-arm64 and windows-386. Locally, versions are stored under a broth directory (for example ~/.config/itch/broth/ on Linux), with extracted binaries, temporary downloads and a .chosen-version marker. Version selection uses semver constraints defined in src/main/broth/formulas.ts (butler ^15.20.0, itch-setup ^1.8.0). The app fetches a /versions endpoint and picks the newest version satisfying the constraint; canary builds use -head channels with no constraints. On startup it validates the chosen version, checks for new component versions when the app version changed, downloads and extracts with CRC32 verification, runs a sanity check, then updates the marker and cleans up old versions. A development override (BROTH_USE_LOCAL=butler) allows using a locally built butler. butlerd bindings Communication with butler uses a JSON-RPC 2.0 protocol called butlerd. TypeScript definitions for requests, notifications and data types live in src/common/butlerd/messages.ts and are autogenerated from Go type definitions using a tool called generous. The generated code depends on the @itchio/butlerd npm package, which provides the runtime for launching the daemon, connecting over TCP and exchanging JSON-RPC messages. Bindings can be regenerated with npm run sync-butler when the butler repository is checked out as a sibling directory. itch vs. kitch The codebase supports two variants: itch (stable) and kitch (canary), installable side by side. The variant is determined by the git tag at build time: a tag ending in -canary produces kitch, otherwise itch. Local development always runs as kitch because package.json's name defaults to "kitch"; production packaging overwrites it to "itch" for non-canary builds. Differences include URL protocols (itchio:// and itch:// versus kitchio:// and kitch://), broth channels (regular versus -head), semver constraints (present versus none), macOS bundle IDs, tray/window icons, and artifact names. Development and testing Development requires npm install, then npm start to run in development mode with watching and rebuilding. Other scripts include npm run ts-check for type checking and npm run compile to build assets. Integration tests use ChromeDriver to control the Electron app and exercise flows such as logging in, installing games and navigating the UI. They require Go (the test runner is written in Go), a display (xvfb on Linux CI), and an itch.io API key from a test account. The ChromeDriver version must match the Electron version; when the Electron version in package.json changes, integration-tests/versions.go must be updated accordingly. Tests can run against a packaged build (npm run integration-tests) or the development version (node release/test.js --test-dev). License and related projects itch is released under the MIT License. The README also mentions Mitch, an Android client started by other developers.