{"id":13512484,"url":"https://github.com/itchio/itch","last_synced_at":"2026-02-19T06:05:37.716Z","repository":{"id":31683799,"uuid":"35249369","full_name":"itchio/itch","owner":"itchio","description":"🎮 The best way to play your itch.io games","archived":false,"fork":false,"pushed_at":"2024-10-19T15:05:20.000Z","size":35802,"stargazers_count":2479,"open_issues_count":804,"forks_count":222,"subscribers_count":69,"default_branch":"master","last_synced_at":"2025-04-10T00:10:53.951Z","etag":null,"topics":["electron","game-development","itchio","typescript"],"latest_commit_sha":null,"homepage":"https://itch.io/app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itchio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-07T23:58:36.000Z","updated_at":"2025-04-09T08:26:50.000Z","dependencies_parsed_at":"2023-11-29T23:31:21.039Z","dependency_job_id":"6ba64ed8-bfd3-4d9a-955c-1ba74cab64bc","html_url":"https://github.com/itchio/itch","commit_stats":{"total_commits":7924,"total_committers":482,"mean_commits":"16.439834024896264","dds":0.7382635032811711,"last_synced_commit":"0c80bf9bf28af1cda1c9b36696b552912aa7b2a1"},"previous_names":[],"tags_count":410,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itchio%2Fitch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itchio%2Fitch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itchio%2Fitch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itchio%2Fitch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itchio","download_url":"https://codeload.github.com/itchio/itch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251562241,"owners_count":21609517,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electron","game-development","itchio","typescript"],"created_at":"2024-08-01T03:01:55.156Z","updated_at":"2026-02-19T06:05:37.710Z","avatar_url":"https://github.com/itchio.png","language":"TypeScript","readme":"# itch\n\n![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)\n![Built with love](https://img.shields.io/badge/built%20with-%E2%9D%A4-FF8080.svg)\n[![build](https://github.com/itchio/itch/actions/workflows/build.yml/badge.svg)](https://github.com/itchio/itch/actions/workflows/build.yml)\n[![Translation status](https://weblate.itch.zone/widgets/itchio/-/itch/svg-badge.svg)](https://weblate.itch.zone/engage/itchio/?utm_source=widget)\n\nThe goal of this project is to give you a desktop application that you can\ndownload and run games from [itch.io](http://itch.io) with. Additionally you\nshould be able to update games and get notified when games are updated. The\ngoal is not to replace the itch.io website.\n\n## Screenshots\n\n![](https://static.itch.io/images/app/collections@1x.png)\n\n![](https://static.itch.io/images/app/gamepage@1x.png)\n\n![](https://static.itch.io/images/app/install@1x.png)\n\n## Downloads\n\nYou can download it from \u003chttps://itch.io/app\u003e, see [Installing the app](https://itch.io/docs/itch/installing/) for\ndetailed instructions.\n\nIf you'd like to develop the app instead, read the [Getting Started][developing] page of the developer guide.\n\n[developing]: https://itch.io/docs/itch/developing/getting-started.html\n\n## Development Quick Start\n\n```bash\n# Install dependencies\nnpm install\n\n# Start the app in development mode (watches for changes and rebuilds)\nnpm start\n\n# Type check the project\nnpm run ts-check\n\n# Build assets\nnpm run compile\n\n# Use a local/development version of butler instead of the bundled one\nBROTH_USE_LOCAL=butler npm start\n```\n\n## App Architecture\n\nThe itch desktop app consists of three components working together:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    itch (Electron App)                      │\n│  ┌─────────────────────┐    ┌────────────────────────────┐  │\n│  │   Main Process      │    │   Renderer Process         │  │\n│  │   (Node.js)         │◄──►│   (React)                  │  │\n│  │                     │    │                            │  │\n│  │ • State (Redux)     │    │ • UI components            │  │\n│  │ • Reactors          │    │ • User interactions        │  │\n│  │ • Process mgmt      │    │ • State display            │  │\n│  └──────────┬──────────┘    └────────────────────────────┘  │\n└─────────────┼───────────────────────────────────────────────┘\n              │ TCP/RPC\n              ▼\n┌─────────────────────────────┐   ┌───────────────────────────┐\n│         butler              │   │       itch-setup          │\n│       (Go daemon)           │   │     (Go executable)       │\n│                             │   │                           │\n│ • Game downloads/installs   │   │ • App installation        │\n│ • Launch management         │   │ • Self-updates            │\n│ • SQLite database           │   │                           │\n└─────────────────────────────┘   └───────────────────────────┘\n              ▲                              ▲\n              └──────── broth.itch.zone ─────┘\n                    (binary distribution)\n```\n\n### itch (This Repository)\n\nAn Electron app with a multi-process architecture:\n\n- **Main Process**: Handles state management (Redux), business logic, and coordination with butler/itch-setup. Uses a \"reactor\" pattern to handle side effects from Redux actions.\n- **Renderer Process**: React-based UI with state synchronized from the main process via electron-redux.\n\n### butler\n\nA Go daemon ([itchio/butler](https://github.com/itchio/butler)) that handles all game operations:\n\n- Downloads, installs, updates, and launches games\n- Maintains a SQLite database for installation data\n- Communicates with itch via TCP-based RPC\n- Spawned as a child process, tied to itch's lifecycle\n\n### itch-setup\n\nA Go executable ([itchio/itch-setup](https://github.com/itchio/itch-setup)) for installation and updates:\n\n- Handles initial app installation on all platforms\n- Manages self-update checks and restarts\n\n### Version Management (broth)\n\nThe itch app automatically manages butler and itch-setup versions through the\n\"broth\" system. Broth is a service we run that proxies over the itch.io API to\nprovide fixed download URLs for binaries \u0026 assets related to the itch app.\n\n**Remote Distribution:**\n- Binaries are hosted at `https://broth.itch.zone/{package}/{platform}/{version}`\n- Platform format: `{os}-{arch}` (e.g., `linux-amd64`, `darwin-arm64`, `windows-386`)\n\n**Local Storage** (eg. `~/.config/itch/broth/` on Linux):\n```\nbroth/\n├── butler/\n│   ├── versions/{version-hash}/butler    # Extracted binary\n│   ├── downloads/                        # Temporary during download\n│   └── .chosen-version                   # Currently active version\n└── itch-setup/\n    └── [same structure]\n```\n\n**Version Selection:**\n- Uses semver constraints defined in `src/main/broth/formulas.ts`:\n  - butler: `^15.20.0`\n  - itch-setup: `^1.8.0`\n- Fetches `/versions` endpoint and picks the newest version satisfying the constraint\n- Canary builds use `-head` channels with no constraints (always latest)\n\n**Upgrade Flow:**\n1. On startup, validates `.chosen-version` against installed marker\n2. If app version changed since last run, checks for new component versions\n3. Downloads zip, extracts with CRC32 verification, runs sanity check\n4. Updates `.chosen-version` and cleans up old versions\n\n**Development Override:**\n```bash\n# Use locally-built butler instead of managed version\nBROTH_USE_LOCAL=butler npm start\n```\n\nKey source files: `src/main/broth/package.ts`, `src/main/broth/formulas.ts`, `src/main/broth/manager.ts`\n\n### butlerd Bindings\n\nThe itch app communicates with butler via a JSON-RPC 2.0 protocol called **butlerd**. The TypeScript type definitions for all RPC requests, notifications, and data types live in `src/common/butlerd/messages.ts`. This file is autogenerated from Go type definitions in the butler repository using a tool called **generous**.\n\nThe generated code depends on the [`@itchio/butlerd`](https://github.com/itchio/node-butlerd) npm package, which provides the runtime for communicating with the butler daemon (launching it, connecting over TCP, and sending/receiving JSON-RPC messages). The generated `messages.ts` imports `createRequest` and `createNotification` helpers from this package.\n\nTo regenerate the bindings after changes to butler's API:\n\n```bash\n# Requires the butler repo checked out as a sibling directory (../butler)\nnpm run sync-butler\n```\n\nThis runs the **generous** tool (`butler/butlerd/generous/`) in `ts` mode, which parses Go structs and their comment annotations (e.g. `@name`, `@category`, `@caller`) to produce TypeScript interfaces, enums, and request/notification helpers. The generated `messages.ts` should be committed to this repo. See the butler repo's README for more on the generous tool and regenerating butler-side generated files.\n\nSee \u003chttps://docs.itch.zone/butlerd/master/\u003e for the butlerd API documentation.\n\n## kitch vs. itch\n\nThe codebase supports two app variants: **itch** (stable) and **kitch** (canary). They can be installed side-by-side and are distinguished by the git tag used at build time — a tag ending in `-canary` (e.g. `v0.1.2-canary`) produces kitch, anything else produces itch. The development version of the app (started with `npm start`) will run in kitch mode.\n\n### How the variant is determined\n\n- **At build time**: `release/common.js` inspects the git tag. A `-canary` suffix selects kitch; otherwise itch. The `name` field in `package.json` is `\"kitch\"` by default, so **local development always runs as kitch**. During production packaging, the name is overwritten to `\"itch\"` for non-canary builds.\n- **At runtime**: `src/main/env.ts` calls `app.getName()` (which returns the `name` from `package.json`) to set `env.isCanary`, `env.appName`, and `env.channel`.\n\n### Key differences\n\n| Area | itch (stable) | kitch (canary) |\n|------|--------------|----------------|\n| URL protocols | `itchio://`, `itch://` (production only) | `kitchio://`, `kitch://` |\n| Broth channels | Regular (e.g. `darwin-amd64`) | `-head` suffix (e.g. `darwin-amd64-head`) |\n| Semver constraints | butler `^15.20.0`, itch-setup `^1.8.0` | None (always latest) |\n| macOS bundle ID | `io.itch.mac` | `io.kitch.mac` |\n| Tray/window icons | `src/static/images/tray/itch.png`, `src/static/images/window/itch/` | `src/static/images/tray/kitch.png`, `src/static/images/window/kitch/` |\n| Binary/artifact name | `itch` | `kitch` |\n\n## Integration Tests\n\nThe project includes integration tests that use ChromeDriver to control the Electron app and test user flows like logging in, installing games, and navigating the UI.\n\n### Requirements\n\n- **Go**: The test runner is written in Go and must be compiled before running\n- **Desktop environment**: Tests require a display (on Linux CI, `xvfb` is used)\n- **itch.io API key**: Tests authenticate using an API key from a specific test account\n\n### ChromeDriver Version\n\nThe integration tests download a specific ChromeDriver version that must match the Electron version used by the app. If you update the Electron version in `package.json`, you must also update `integration-tests/versions.go` to match:\n\n```go\nconst electronVersion = \"33.4.11\"  // Must match package.json electron version\nconst chromeDriverVersionString = \"ChromeDriver 130.0.6723.191\"  // Chrome version for that Electron\n```\n\nTo find the correct Chrome version for an Electron release, check the [Electron Releases](https://releases.electronjs.org/) page.\n\n### Running the Tests\n\n```bash\n# Set the API key for the test account (itch-test-account)\nexport ITCH_TEST_ACCOUNT_API_KEY=\"your-api-key\"\n\n# Run integration tests against a packaged build\nnpm run integration-tests\n\n# Run against the development version (faster iteration, no packaging step)\nnode release/test.js --test-dev\n\n# Run fresh (clear cached chromedriver and test artifacts)\nrm -rf integration-tests/.chromedriver integration-tests/tmp integration-tests/screenshots\nnode release/test.js --test-dev\n```\n\nThe `--test-dev` flag runs tests against the development version of the app instead of requiring a packaged production build. This is useful for faster iteration during development.\n\n## License\n\nitch is released under the MIT License, see the [LICENSE][] file for details.\n\n[LICENSE]: LICENSE\n\n## Other relevant projects\n\nHere are some other apps people have started:\n\n### Android\n* [Mitch](https://gardenapple.itch.io/mitch)\n\n","funding_links":[],"categories":["Applications","TypeScript","IOS","Maps/Hacks/Plugins/Utilities/All of the Things™"],"sub_categories":["Games","iOS"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitchio%2Fitch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitchio%2Fitch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitchio%2Fitch/lists"}