- webapp/admin/: a second Vite entry (/admin/, HashRouter), served only by the Worker after the Access check, with its own CSP. Review queue by status (approve, approve with override for previously removed games, reject), paste-to-add URLs, and a catalog editor for the three maintainer fields, removal with a public reason, and restore of removed games. Uses the published /data for search; every write is applied to the latest repository state by the Worker. An expired Access session surfaces as "sign in again" instead of a broken request. - /suggest (web only; the desktop/Android apps link to the website): itch.io link + optional note (<= 500 characters, deleted after 180 days), Cloudflare Turnstile loaded on demand, EN + VI strings. - Local development: DEV_ADMIN_EMAIL in .dev.vars lets `wrangler dev` on localhost into the admin without Access; it is ignored on any other host. Checked in wrangler dev with a local D1: queue listing, reject, approve answering "GitHub App not configured", catalog search/editor, and a Suggest submission (Turnstile test keys) landing in the queue; no CSP violations. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Free Itch.io Games List
🇻🇳 Tiếng Việt: see
README.vi.md. Vietnamese translations of the policy docs live indocs/i18n/vi/. The English versions in this repo remain controlling for legal interpretation.
A curated, auto-updating catalog of free games on itch.io. Games are scraped, validated, and published as a browsable, filterable website — https://freeitchgames.win — refreshed daily via GitHub Actions.
Table of contents
- Browse the catalog
- Webapp (browse + edit + analytics)
- How it works
- Project structure
- Automation (GitHub Actions)
- Data fields
- Contributing
- Legal
Browse the catalog
The catalog lives on the website: https://freeitchgames.win — search, filter by genre / platform /
status, sort, and open any game on itch.io. (The per-genre markdown tables under lists/ were retired in
favour of the site.) The raw data is plain JSON in data_game/.
Webapp (browse + edit + analytics)
A React + TypeScript SPA in webapp/ provides a browsable UI on top of the same JSON
catalog: virtualized DataTable for all 2,600+ games, faceted filters (genre / status / platforms /
NSFW), 16 charts (Recharts), bulk edit/delete via the GitHub Git Data API, and a one-click "add"
flow that dispatches the scraper workflow with a URL input.
- Web build: deployed to https://freeitchgames.win by Cloudflare Workers Builds from
webapp/wrangler.jsonc— every push tomainships automatically (no GitHub Actions deploy). The old GitHub Pages address only redirects there. - Desktop build (optional): same React code wraps as a Tauri 2 native app for Windows / macOS
/ Linux. See
webapp/TAURI.mdfor prerequisites andnpm run tauri:dev. Multi-platform installers are built by.github/workflows/release_desktop.ymlon tag push (v*). - Android build (optional): the same app also ships as a sideloadable
.apk(arm64-v8a) via Tauri mobile. A signed APK is built by.github/workflows/release_android.ymland attached to the same draft Release. See Android (download & install) below and the Android section ofwebapp/TAURI.md. - Auth: a fine-grained PAT with
contents:write+workflow:writeis encrypted in localStorage with a passphrase (AES-GCM, PBKDF2-SHA256). Decrypted token only lives in memory. Reads are public (no auth needed). - Edits commit as
chore(webapp): …so they're easy to filter from the daily scraper commits.
Local dev:
cd webapp
npm install
npm run dev # http://localhost:5173
npm run build # writes to webapp/dist/
npm run tauri:dev # native desktop (requires Rust)
Android (download & install)
No Play Store — just grab the .apk and sideload it (Android is fine with this, it just
asks nicely first):
- Open the latest Release and
download
FreeGamesItchio_<version>_arm64-v8a.apk. - Tap it. Android will ask to allow installs from this source (browser / file manager) — turn it on (Settings → Apps → Special access → Install unknown apps).
- Accept the "not from Play Store" warning and install. It's the same app as the web/desktop build, just signed by me instead of Google.
Notes: arm64-v8a only (every phone since ~2017 — 32-bit-only devices aren't supported), and
Android 11+ (API 30). Older versions can't install it — that's deliberate: it keeps the floor
at a release that still gets security hardening and that we actually test on (≈87% of active
devices; why). Building it yourself is in the Android
section of webapp/TAURI.md.
How it works
temp_link.json ─→ update_info.py ─┐ ┌─→ data_game/*.json ─→ freeitchgames.win
(queued URLs) (scrape, free?) ├─→ patch.json ─→ apply_patch.py
data_game/ ─→ refresh.py ──┘ (URL-keyed) (validate + push)
(1/7 per day) (alive / paid / rating / status)
- Add links — itch.io URLs are queued in
scripts/temp_link.json(by the companion browser extension, or manually / via PR). - Ingest —
update.ymlrunsupdate_info.pyas soon as the queue changes (and daily as a fallback). Each link is canonicalized, fetched, checked for free status and scraped; paid, dead, duplicate and previously removed games are skipped. Transient failures stay queued and are retried (up to 3 runs). - Refresh —
refresh.ymlchecks one seventh of the catalog every day (one request per game), so every game is re-checked weekly: dead links (404/410), games that became paid, rating and status. A game is only removed when the same problem is seen again at least 20 hours later; removals are logged with a reason, and a run that would remove an implausible number of games holds them back and alerts instead. - Commit safely — both steps emit a URL-keyed patch;
apply_patch.pyapplies it to the latestmain, validates every data file (validate.py) and only then pushes, retrying if another writer got there first.
Project structure
data_game/ # Game database (chunked JSON, max 500 per file)
├── game_info_001.json
├── game_info_002.json
└── ...
scripts/
├── scraper.py # Shared: HTTP session, pacing / 429 back-off, free detection, parsing
├── data_store.py # Shared: chunked load/save (minimal diffs), index.json, count_history.json
├── canonical.py # One canonical form for itch.io game URLs
├── update_info.py # Queued URLs → patch (new games)
├── refresh.py # Rotating health check → patch (alive / paid / rating / status); --full re-scrape
├── apply_patch.py # Apply a patch to the latest main, then validate
├── validate.py # Schema + consistency checks for every data file
├── temp_link.json # Input queue for new URLs
├── deleted_games.json # Log of removed games with reasons
└── state/ # Pipeline bookkeeping (last check, strikes, retries) — not published
bash/commit_push.sh # fetch main → apply patch → validate → commit → push (with retries)
tests/ # pytest suite (no network) + fixtures shared with the web Worker
.github/workflows/
├── update.yml # Ingest queued games (on queue change + daily)
├── refresh.yml # Daily rotating catalog check
├── force_update.yml # Manual full re-scrape (one URL or the next batch)
├── python-ci.yml # Lint, tests, data validation
├── webapp-ci.yml # Lint, type-check, build (no deploy)
├── release_desktop.yml # Build Tauri installers (Win/macOS/Linux) on v* tag
└── release_android.yml # Build signed Android APK (arm64-v8a) on v* tag
webapp/ # React + TS SPA + Tauri desktop & Android wrapper
├── src/ # React app (routes, components, hooks, stores)
├── src-tauri/ # Rust + Tauri 2 config (icons, capabilities, main.rs)
├── TAURI.md # Desktop build prerequisites and instructions
├── package.json
├── vite.config.ts
└── tailwind.config.ts
Automation (GitHub Actions)
| Workflow | Schedule | Purpose |
|---|---|---|
| Ingest queued games | On queue change + daily 01:23 UTC | Scrape links from temp_link.json (+ optional url input), skip paid / dead / removed |
| Refresh catalog | Daily 02:47 UTC | Check 1/7 of the catalog: dead links, now-paid games, rating, status |
| Force update | Manual | Re-scrape every field (one URL or the next batch); keeps safe_virus / notes / nsfw |
| Python CI / Webapp CI | Pull requests | Lint, tests, data validation / type-check and build |
| Deploy webapp | On push to main | Cloudflare Workers Builds (webapp/wrangler.jsonc) → freeitchgames.win |
| Release desktop | On v* tag push |
Build Tauri installers (Win/macOS/Linux) → draft Release |
| Release Android | On v* tag push |
Build signed APK (arm64-v8a) → draft Release |
Scrapers identify themselves (FreeItchGamesBot), pace requests (random delays, batch pauses) and back off on
HTTP 429. Network errors are treated as transient; a game is removed only after the same 404/410 or paid status is
seen again at least 20 hours after the first sighting. Failures, cancellations, rate limits and
suspicious mass changes are reported to Discord.
Data fields
Each game entry in data_game/game_info_NNN.json contains:
| Field | Description |
|---|---|
url |
Game page URL |
name |
Game title |
dev |
Developer / author name(s) |
description |
Short description (first sentence, max 200 chars) |
genre |
Genre(s) from itch.io |
tags |
All tags |
status |
Release status |
platforms |
Available platforms (Windows, macOS, Linux, Web) |
publisher |
Publisher (if different from author) |
release_date |
Full release date from page metadata |
made_with |
Engine / tools used |
rating |
Average rating (from itch.io aggregate) |
rating_count |
Number of ratings |
average_session |
Typical play session length |
languages |
Supported languages |
inputs |
Input methods (keyboard, mouse, gamepad) |
nsfw |
NSFW flag (auto-detected from tags, warnings, description) |
safe_virus |
Manual safety note (default: ?) |
notes |
Manual notes |
thumbnail |
Thumbnail image URL |
All fields default to N/A when not available on the game page.
Contributing
See CONTRIBUTING.md for full details.
- Add games — use the "Add New Games" issue template (max 50 links per issue).
- Add games via Telegram bot — alternative path for batch submissions through @my_skull_bot; DM the owner to be whitelisted. Full flow + privacy notes: CONTRIBUTING §1b · Bot repo: poli0981/telegram-scraper-bot (USER_GUIDE.md).
- Report bugs — use the "Bug Report" template.
- Request features — open an issue or submit a PR.
Contributors are credited in ACKNOWLEDGEMENTS.md.
Maintainer hardware + dev environment: docs/pc_spec.md, docs/dev_env.md.
Connect / support
Two Discord servers exist now (the "if I ever make one" disclaimer is officially obsolete):
- Chat: Discord — Repo discussion · Game chat
- Social: X/@SkullMute0011 · YouTube/@SkullMute · Bluesky · Mastodon
- Messaging: Telegram (DM) · Telegram bot — game submission (DM your numeric ID privately, never in public channels)
- Support (totally optional, mirrors
.github/FUNDING.yml): GitHub Sponsors · Patreon · Ko-fi · Buy Me a Coffee · PayPal - Gaming: Steam profile
DMs are open everywhere — replies slow, introvert max level. The About page in the webapp has the same list with one-click buttons.
Legal
Licensed under MIT.