poli0981andClaude Fable 5 af8dd83157 release(v3.6.0): i18n EN/VI, offline cache, custom error pages (#55)
- Minimal typed i18n layer (~454 keys) with lazy-loaded Vietnamese dictionary
  chunk; language switcher in Settings, preference persisted in webapp.prefs
- Persist react-query catalog cache to IndexedDB (instant paint on revisit,
  background revalidation; buster = app version, maxAge 7 days)
- Status-aware error pages (400-504, 419, offline, unknown) wired into every
  route via typed HttpError; route ErrorBoundary with new-version reload;
  hidden /errors/:code preview route; static 404.html for GitHub Pages
- Perf polish: GameThumb onError fallback, lazy settings avatar, DEV-gated
  react-query devtools
- npm audit fix: react-router 7.14.2 -> 7.17.0 (GHSA-8x6r-g9mw-2r78)
- Bump version badges, about.ts APP.version, CHANGELOG to 3.6.0

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-06-12 20:00:25 +07:00
2026-06-11 08:35:51 +00:00
2026-06-11 08:36:02 +00:00
2026-06-11 08:35:51 +00:00
2026-01-11 20:36:53 +07:00
2025-12-28 16:37:25 +07:00
2025-12-20 11:57:11 +07:00

Free Itch.io Games List

Version Stars Forks Last Updated License: MIT Tiếng Việt

🇻🇳 Tiếng Việt: see README.vi.md. Vietnamese translations of the policy docs live in docs/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 organized into browsable markdown tables — updated daily via GitHub Actions.

Table of contents

Browse by genre

Tables are auto-generated and split by primary genre (max 300 games per file). New genres appear automatically as games are added.

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 500+ 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 GitHub Pages by .github/workflows/deploy_webapp.yml — pushes to main that touch webapp/ ship automatically. (One-time setup: repo Settings → Pages → Source = "GitHub Actions".)
  • Desktop build (optional): same React code wraps as a Tauri 2 native app for Windows / macOS / Linux. See webapp/TAURI.md for prerequisites and npm run tauri:dev. Multi-platform installers are built by .github/workflows/release_desktop.yml on tag push (v*).
  • Auth: a fine-grained PAT with contents:write + workflow:write is 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 docs/app/
npm run tauri:dev    # native desktop (requires Rust)

How it works

temp_link.json          →   update_info.py        →   data_game/
(new URLs added here)       (scrape + free check)     game_info_001.json
                                                      game_info_002.json ...
                                                          │
                ┌─────────────────────────────────────────┘
                ▼                                        ▼
        generate_md.py                           check_paid.py
        (MD tables)                              check_alive.py
                                                 (cleanup)
  1. Add links — paste itch.io URLs into scripts/temp_link.json (manually, via PR, or via the companion browser extension).
  2. Daily scrape — GitHub Actions runs update_info.py at 03:00 UTC. Each link is fetched, checked for free status, and scraped for metadata. Paid games are automatically skipped.
  3. Generate tables — generate_md.py groups games by primary genre and outputs markdown tables into /lists/.
  4. Periodic cleanup — every 2 days, check_paid.py re-checks if any game in the list became paid, and check_alive.py verifies that game pages still exist. Removed games are logged with a reason.

Project structure

data_game/              # Game database (chunked JSON, max 500 per file)
├── game_info_001.json
├── game_info_002.json
└── ...

scripts/
├── scraper.py          # Shared module: session, rate-limiting, free detection, parsing
├── data_store.py       # Shared module: multi-file load/save/rebalance
├── update_info.py      # Scrape new games from temp_link.json → data_game/
├── check_paid.py       # Re-check existing games for paid status
├── check_alive.py      # Verify game URLs still exist (404/410 → remove)
├── generate_md.py      # Generate per-genre markdown tables
├── log_deleted.py      # Export deleted_games.json → deleted_games.txt
├── temp_link.json      # Input queue for new URLs
└── deleted_games.json  # Log of removed games with reasons

bash/
├── test.sh             # Wrapper: scrape + reset temp_link
├── table.sh            # Wrapper: generate MD tables
├── check_paid.sh       # Wrapper: check paid status
├── check_alive.sh      # Wrapper: check dead links
└── log_deleted.sh      # Wrapper: export deletion log

lists/                  # Auto-generated markdown tables (one per genre)

.github/workflows/
├── update.yml             # Daily 03:00 UTC — scrape new games
│                          # (also accepts an optional `url` input from webapp)
├── generate_table.yml     # Runs after update/check workflows
├── check_paid.yml         # Every 2 days 04:00 UTC
├── check_alive.yml        # Every 2 days 07:00 UTC
├── log_deleted.yml        # Runs after check workflows
├── deploy_webapp.yml      # Build webapp/ → GitHub Pages on push to main
└── release_desktop.yml    # Build Tauri installers (Win/macOS/Linux) on v* tag

webapp/                 # React + TS SPA + Tauri desktop 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
Update game info Daily 03:00 UTC Scrape new links from temp_link.json (+ optional url input from webapp), skip paid
Generate tables After update/checks Rebuild markdown tables in /lists/
Check paid games Every 2 days 04:00 UTC Remove games that became paid
Check dead links Every 2 days 07:00 UTC Remove 404/410 game pages
Log deleted games After check workflows Export deletion log to deleted_games.txt
Deploy webapp On push to main Build webapp/ → GitHub Pages (docs/app/)
Release desktop On v* tag push Build Tauri installers (Win/macOS/Linux) → draft Release

All workflows include rate-limiting (random delays, batch pauses) to avoid being blocked by itch.io. Network errors are treated as transient — games are only removed on confirmed 404/410 or confirmed paid status.

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):

DMs are open everywhere — replies slow, introvert max level. The About page in the webapp has the same list with one-click buttons.

Licensed under MIT.

S
Description
No description provided
Readme CC-BY-4.0
12 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 81.7%
Python 13.8%
JavaScript 1.3%
Rich Text Format 1.1%
CSS 1%
Other 1.1%