dependabot[bot] f8ed564c12 chore(deps): Bump jose from 6.2.15 to 6.2.17 in /webapp
Bumps [jose](https://github.com/panva/jose) from 6.2.15 to 6.2.17.
- [Release notes](https://github.com/panva/jose/releases)
- [Changelog](https://github.com/panva/jose/blob/main/CHANGELOG.md)
- [Commits](https://github.com/panva/jose/compare/v6.2.15...v6.2.17)

---
updated-dependencies:
- dependency-name: jose
  dependency-version: 6.2.17
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-11-15 18:35:10 +00:00
2026-11-15 16:24:29 +00:00

Free Itch.io Games List

Version Status: stable, maintenance only Website Stars Forks Last Updated Python CI Quality gate Coverage Qodana Accessibility: WCAG 2.2 AA target Code: MIT Data & docs: CC BY 4.0 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 5,900+ free games on itch.io. Browse it at https://freeitchgames.win: search, filter, sort, and jump to any game's itch.io page. The site is read-only for everyone: no accounts, no sign-in, no comments, no ads, no payments.

Project status

Stable, maintenance only (since version 4.6.1, 2026-11-11). The project is feature-complete: the website, the apps and the data pipeline keep running, and the catalog keeps updating itself every day.

  • What still happens: security fixes (CVEs and reports made through SECURITY.md), runtime and dependency updates (Node.js, Python, Rust, npm / pip / cargo packages, GitHub Actions), and repairs when something stops the site or the daily data updates from working.
  • What no longer happens: new features, redesigns and refactors. Feature requests and code pull requests are closed without review.
  • Issues and pull requests are for the data only: adding games, fixing a game's data, removing a game. See Contributing.

Table of contents

Browse the catalog

Everything lives on the website, https://freeitchgames.win:

  • Games: the whole catalog in one fast table (a compact list on phones), with filters for genre, platform, status, the creator's generative-AI disclosure, accessibility and more, plus a detail page for every game.
  • Charts: how the catalog breaks down, and how it has grown over time.
  • Removed: every game dropped from the catalog, with the reason (https://freeitchgames.win/removed).
  • A quick check first. Your first visit, then about once every 48 hours, starts with a short Cloudflare Turnstile check that keeps bots out. It usually passes by itself and then opens the page you asked for. The catalog data under /data and the apps don't need it.
  • 18+ content is hidden by default. Games flagged nsfw: Yes stay hidden (covers included) unless you opt in under Settings after confirming you are 18 or older. That choice is stored only in your browser.
  • Made for every way of browsing. Everything works with the keyboard alone and with screen readers, colours meet the WCAG contrast ratios in both themes, every chart has a data table, and the site follows your system's reduced-motion and contrast settings. What works, the known gaps and how to report a barrier: ACCESSIBILITY.md.

Every link goes to the game's own page on itch.io. Cover images on the website are resized copies served by freeitchgames.win, so your browser does not contact itch.io until you click a link.

Want the raw data? It is plain JSON in data_game/ (plus scripts/deleted_games.json) in this repo: clone it, download it, or read the raw files. Please use those instead of scraping the website, which serves its own compact format; see License for how you may reuse them.

(The old address, poli0981.github.io/free-games-itchio-list, only redirects to the new site. The per-genre markdown tables under lists/ and deleted_games.txt are gone: the catalog is web-only.)

Desktop and Android apps

The same app also ships as native read-only viewers, built with Tauri 2 from the same code. Grab them from the latest GitHub Release:

Platform Files
Windows .msi or .exe installer
macOS .dmg, .pkg or .app.tar.gz (needs Safari/WebKit 16.4 or newer)
Linux .deb, .rpm or .AppImage
Android 11+ (arm64-v8a) .apk (sideloaded, see below)

The apps download the catalog data from https://freeitchgames.win/data and load cover images directly from itch.io's image CDN (img.itch.zone); clicking a game opens itch.io in your browser. No telemetry. Updates are manual: download a new release when one comes out. Installing an app means accepting the EULA.

Android (download & install)

No Play Store: just grab the .apk and sideload it (Android is fine with this, it just asks nicely first):

  1. Open the latest Release and download FreeGamesItchio_<version>_arm64-v8a.apk. Only install the APK from that page: it is signed with the project's key.
  2. Tap it. Android will ask to allow installs from this source (browser / file manager). Turn it on (Settings → Apps → Special access → Install unknown apps).
  3. Accept the "not from Play Store" warning and install. It's the same app as the web/desktop build.

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.

Add a game

There are three ways a game gets into the catalog. Each is approved by the Maintainer, one by one in the review queue or through automatic rules the Maintainer sets.

  1. Suggest page: https://freeitchgames.win/suggest. Paste an itch.io game link and, if you like, a short note (up to 500 characters; notes are deleted after 180 days). A Cloudflare Turnstile check and a rate limit keep spam out. Please don't put personal data in the note.
  2. Automatic discovery: every 4 hours the site reads one of itch.io's public RSS feeds of new and popular free games (one feed per run) and queues what it finds.
  3. Followed collections: the site also reads the public itch.io collections the Maintainer follows and queues their new free games directly (one removed before, or with a warning flag, goes to the review queue instead).

The Maintainer's browser extension and the old Telegram bot are retired; their repositories (itch-f2p-extension, telegram-scraper-bot) are archived.

The Maintainer reviews the queue in a private admin area (protected by Cloudflare Access); an item without a warning flag that nobody rejected within a waiting time (24 hours by default) is approved automatically. Approved links are handed to the data pipeline, which scrapes each game page; paid games are dropped.

Prefer GitHub, or have a long list? The "Add Games (bulk list)" issue template works too; those links go through the same review. See CONTRIBUTING.md.

Want a game removed, or its data corrected (game creators especially)? Email takedown@poli0981.dev or open a "Remove a game" issue. Include the game URL, who you are (creator / rights holder, or authorized by them) and the reason. Details: Terms of Use and Disclaimer.

How the data stays fresh

Suggest page ──┬─→ review queue ─→ Maintainer approves ─→ scripts/temp_link.json
RSS feeds    ──┘               (admin, or auto rules)         │
Followed collections ─────────────────────────────────────────┤
                                                              ▼
                         update.yml → update_info.py (new games) ──┐
                         refresh.yml → refresh.py (1/7 per day)  ──┴─→ patch ─→ apply_patch.py
                                                                          (validate + push)
                                                                                 │
                                          freeitchgames.win/data ←── data_game/*.json
  1. Queue: approved links are committed to scripts/temp_link.json by the project's GitHub App (verified commits).
  2. Ingest: update.yml runs update_info.py as 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).
  3. Refresh: refresh.yml re-checks 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 in scripts/deleted_games.json, and a run that would remove an implausible number of games holds them back and alerts instead.
  4. Commit safely: both steps emit a URL-keyed patch; apply_patch.py applies it to the latest main, validates every data file (validate.py) and only then pushes, retrying if another writer got there first.
  5. Publish: every push to main rebuilds the website, which bundles the catalog under https://freeitchgames.win/data.

The pipeline is polite to itch.io: it identifies itself as FreeItchGamesBot/4.0 (+https://freeitchgames.win/about), paces its requests and honours HTTP 429 / Retry-After. Only public itch.io pages and feeds are read.

Under the hood

  • Web app (webapp/src/): React + TypeScript + Vite + Tailwind CSS, TanStack Query, React Router, Zustand. English and Vietnamese UI.
  • Cloudflare Worker (webapp/worker/): serves the site and /data, the verification gate (Cloudflare Turnstile), the image proxy (/img, resized WebP covers stored on Cloudflare R2), the Suggest API, the review queue (Cloudflare D1), the admin API and the RSS discovery schedule. Config: webapp/wrangler.jsonc.
  • Admin app (webapp/admin/): the Maintainer-only review screen at /admin, behind Cloudflare Access. It writes to this repo as a GitHub App.
  • Native shell (webapp/src-tauri/): Tauri 2 for Windows, macOS, Linux and Android. See webapp/TAURI.md.
  • Data pipeline (scripts/, Python 3.15): scraper, refresh, patch/apply and validation, run by GitHub Actions.

Deploys happen through Cloudflare Workers Builds (root dir webapp, npm run build, then npx wrangler deploy): every push to main ships automatically.

Quick local dev (full setup, including the Worker, secrets and tests, is in docs/dev_env.md):

cd webapp
npm ci
npm run dev          # http://localhost:5173 (Vite)
npm run build        # writes to webapp/dist/ (the Worker serves it as its assets)
npx wrangler dev     # second terminal: Worker on :8787; Vite proxies /api and /img to it
npm run tauri:dev    # native desktop window (requires Rust)

Project structure

data_game/              # Catalog (chunked JSON, max 500 per file) + LICENSE.md (CC BY 4.0)
├── game_info_001.json
├── ...
├── index.json          # Chunk manifest (total + per-file counts)
└── count_history.json  # Daily totals for the "games over time" chart

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      # Ingest queue (approved links)
├── deleted_games.json  # Log of removed games with reasons (public)
└── state/              # Pipeline bookkeeping (last check, strikes, retries), not published

bash/commit_push.sh     # fetch main → apply patch → validate → commit → push (with retries)
bash/cf_build_status.sh # main's latest Cloudflare Workers Build → Discord on failure (deploy-status.yml)
tests/                  # pytest suite (no network) + fixtures shared with the Worker

webapp/
├── src/                # React app (routes, components, stores, i18n)
├── admin/              # Maintainer-only admin app (/admin)
├── worker/             # Cloudflare Worker (data, image proxy, APIs, review queue, RSS discovery)
├── src-tauri/          # Tauri 2 shell (desktop + Android)
├── wrangler.jsonc      # Cloudflare config
└── TAURI.md            # Desktop / Android build notes

LICENSE                 # MIT (code)
LICENSES/CC-BY-4.0.txt  # Full CC BY 4.0 legal code (data + docs)
NOTICE.md               # License map, non-affiliation, attributions
docs/                   # Policies, dev environment, third-party list (+ Vietnamese mirrors in docs/i18n/vi/)

Automation

Job Schedule Purpose
Ingest (update.yml) On queue change + daily 01:23 UTC Scrape approved links from temp_link.json, skip paid / dead / removed
Refresh (refresh.yml) Daily 02:47 UTC Re-check 1/7 of the catalog: dead links, now-paid or password-protected games, rating, status
Force update (force_update.yml) Manual Re-scrape every field (one URL or the next batch); keeps safe_virus / notes / nsfw
RSS discovery and automatic rules (Cloudflare Worker) Every 4 hours Poll one itch.io feed per run into the review queue; auto-approve unflagged items after the waiting time; queue new free games of followed collections
Python CI / Webapp CI Pull requests (Python CI also on pushes to main that touch it) Lint, tests, data validation / type-check, tests, build
Code analysis (sonarcloud.yml, qodana.yml) Pull requests and pushes to main that change code SonarQube Cloud (with test coverage) and Qodana (TypeScript / JavaScript, Python, Rust)
Deploy website On push to main Cloudflare Workers Builds (webapp/wrangler.jsonc) → freeitchgames.win
Build monitor (deploy-status.yml) Hourly Posts each failed Workers Build of main to Discord, once
Release desktop / Android On v* tag push Tauri installers (Win/macOS/Linux) and signed APK → draft Release

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 the project's Discord as automated notifications.

Data fields

Each game in data_game/game_info_NNN.json has these 20 fields, plus optional added_at / updated_at timestamps added by the pipeline and, since 4.3, the optional ai_disclosure / ai_content / accessibility fields (filled in as each game is re-checked). Only safe_virus, notes and nsfw are maintained by the Maintainer; everything else is scraped from the game's public itch.io page, and no re-scrape ever overwrites those three.

Field Description
url Game page URL
name Game title
dev Developer / author name(s)
description The creator's tagline on itch.io, else the description's 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 18+ flag, Yes / No (suggested from tags, warnings and description when a game is added; maintained by the Maintainer)
safe_virus Manual safety note: ? (default), Yes, No, Caution. A note, not a guarantee: downloads are not scanned
notes Manual notes
thumbnail Cover image URL (on itch.io)
ai_disclosure The creator's generative-AI disclosure: No AI, AI Assisted (itch.io's wording) or N/A (not disclosed)
ai_content What AI was used for when assisted (Graphics, Text, Code, Sounds)
accessibility Accessibility features (Subtitles, Configurable controls, Color-blind friendly, …)

Scraped fields default to N/A when not available on the game page.

Contributing

See CONTRIBUTING.md for the full guide.

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 are slow (introvert max level). The site's About page has the same list with one-click buttons.

License

This repo uses three licenses (full map in NOTICE.md):

What License File
Code: scripts/, webapp/, bash/, workflows, tests, everything not listed below MIT, Copyright (c) 2025-2026 poli0981 (SkullMute) LICENSE
Catalog data: data_game/, scripts/deleted_games.json and the derived files at https://freeitchgames.win/data CC BY 4.0, for the Maintainer's contribution (see below) data_game/LICENSE.md
Documentation: the *.md files in the repo root and docs/ (this README, the policies) CC BY 4.0 LICENSES/CC-BY-4.0.txt

What the data license covers: the selection and arrangement of the collection, the three Maintainer-written fields (safe_virus, notes, nsfw), the removal records, and the structure and derived statistics.

What it does not cover (owned by others, not licensed by this project): game descriptions and any other text written by game creators, cover images / thumbnails and other media, game names, logos and trademarks, and itch.io's trademarks. Plain facts such as URLs, prices and ratings are not copyrightable anyway.

When you reuse the data, please credit it like this:

Free itch.io games catalog by poli0981 (SkullMute) — https://freeitchgames.win — CC BY 4.0

Third-party components keep their own licenses: see docs/THIRD_PARTY.md and the site's About page. The archived browser extension is a separate repo under GPL-3.0. Contributions are accepted under the same license as the part they change (inbound = outbound): MIT for code, CC BY 4.0 for data and docs.

Not affiliated with itch.io. This is an independent fan project. It is not affiliated with, endorsed by, or sponsored by itch.io, Leaf Corcoran or itch corp. "itch.io" and all game names, logos and trademarks belong to their respective owners.

Contact (the Maintainer's own mailbox on poli0981.dev):

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%