Files
free-games-itchio-list/webapp/README.md
T
poli0981andClaude Opus 5.5 047d918d43 feat: accessibility statement, keyboard/screen-reader/chart/contrast fixes; 4.6.0 (#183) [skip-discuss]
Accessibility pass for the website and the apps (WCAG 2.2 AA target) and the accessibility statement: root ACCESSIBILITY.md + docs/i18n/vi/ACCESSIBILITY.md, the accessibility issue form, a default PR template; focus management, the '/' shortcut switch, chart names and data tables, contrast tokens with a CI check, Windows contrast themes; a docs sync of verified mismatches; version 4.6.0 with the two deps sweeps since 4.5.0 (#176, #182).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 14:16:50 +07:00

19 KiB
Raw Blame History

webapp/

One codebase for everything people see of the catalog:

  • the website https://freeitchgames.win — read-only for everyone (no accounts, no sign-in);
  • its Cloudflare Worker — image proxy, the public Suggest form, the admin API and the scheduled RSS discovery;
  • the admin app at /admin/ — Maintainer only, behind Cloudflare Access;
  • the desktop and Android apps — the same public app wrapped with Tauri 2 (see TAURI.md).

Stack: React 19 + TypeScript 7 + Vite 8 (Rolldown) + Tailwind CSS 4 (@tailwindcss/vite, tokens in src/index.css) + shadcn/ui (Radix), TanStack Query, React Router 8, Zustand, and the self-hosted Geist fonts. The Worker is plain TypeScript on Cloudflare Workers (R2, D1, Images, Turnstile, Rate Limiting, Access).

The v3 features (GitHub PAT sign-in, in-app editing, the Add / Workflows pages, GPG commit signing) are gone. On first load the app deletes what v3 left in browser storage (the encrypted token and GPG key entries) and rewrites old #/… links to real paths (src/lib/legacy.ts).

What's in here

Path What
src/ Public app (web + Tauri apps)
admin/ Admin app, built to dist/admin/ (web only)
worker/ Cloudflare Worker (worker/index.ts lists the routes)
worker/migrations/ D1 schema for the review queue
vite-plugins/catalog-data.ts Bundles the catalog into dist/data/ (packs + legacy JSON) + sitemap.xml
public/ Static files; public/_headers sets headers + CSP for them
src-tauri/ Tauri 2 shell for the desktop and Android apps
scripts/ gen_assets.py (PWA icons + OG image), i18n-edit.mjs (edit en/vi keys together), check-tauri-versions.mjs (npm run check:tauri), and the repo-level tests check-csp-hashes.test.mjs (inline script hashes in the CSPs) and check-contrast.test.mjs (WCAG contrast of the colour tokens and the chart palette)
wrangler.jsonc Worker config: assets, bindings, vars, cron, staging env

Local dev

Requires Node.js 26+ (CI uses the version in .node-version) and npm. The full setup, including the Python pipeline, is in docs/dev_env.md.

npm ci
npm run dev        # public app, http://localhost:5173 (serves /data from ../data_game)
npm run build      # tsc -b + vite build → dist/ (app, /admin/, /data, sitemap.xml)
npm run preview    # serve dist/ without the Worker

Vite proxies /api and /img to the Worker on port 8787, so covers, the Suggest form and the admin API only work while it runs. In a second terminal:

npm run build                                            # once: the Worker serves dist/ as its assets
npx wrangler d1 migrations apply freeitchgames --local   # once, and after a new migration
npx wrangler dev                                         # Worker, http://localhost:8787 (= npm run cf:dev)

Local D1 / R2 state lives in .wrangler/ (gitignored). Secrets go in webapp/.dev.vars (gitignored); values there also override the vars in wrangler.jsonc for local runs:

Key Needed for
DEV_ADMIN_EMAIL Admin without Access. Honoured only on localhost / 127.0.0.1 / [::1]
ADMIN_EMAILS Comma-separated admin emails, checked behind Access (not needed with DEV_ADMIN_EMAIL)
TURNSTILE_SECRET Suggest form (with the TURNSTILE_SITEKEY var)
GH_APP_PRIVATE_KEY Admin writes (with the GH_APP_ID / GH_APP_INSTALLATION_ID vars)

A route whose settings are missing answers 503; the public site works without any of them. Details (Suggest from localhost, admin writes, testing the cron) are in docs/dev_env.md.

Path alias @/* → src/*. Vite injects __BUILD_DATE__ for the About page.

Checks

The same steps as webapp-ci.yml:

npm run check:tauri                  # Tauri crates and their npm packages share major.minor
npm run cf:types -- --check          # worker-configuration.d.ts matches wrangler.jsonc
npm run lint                         # ESLint
npm run knip                         # unused files / exports / deps
npm test                             # Vitest: app + Worker (D1 tests run a local workerd)
npm run build                        # includes tsc -b (or run npx tsc -b on its own)
npm run cf:check                     # wrangler deploy --dry-run (deploys nothing)

After editing wrangler.jsonc, run npm run cf:types and commit the regenerated worker-configuration.d.ts. It reads the empty types.env, never .dev.vars, so your local secrets can't leak into it. Secrets are typed by hand in worker/env.ts.

Routes (public app)

Route File Purpose
/ src/routes/welcome.tsx Welcome: catalog status, what the site does, recently added games
/games src/routes/games.tsx Search, filters and sort kept in the URL (src/lib/game-filters.ts); a table on desktop, a list on phones; 100 per page
/games/:slug src/routes/game-detail.tsx Read-only detail view of one game
/charts src/routes/charts.tsx Charts + KPI cards across 4 tabs
/removed src/routes/deleted.tsx Removed games, with reasons (/deleted redirects here)
/suggest src/routes/suggest.tsx Suggest a game (Turnstile, goes to the review queue)
/settings src/routes/settings.tsx Theme, language, density, hide scrollbars, accessibility (the "/" search shortcut), 18+ content opt-in (the header's display menu has most of them)
/about src/routes/about.tsx Project info, legal links, third-party credits
/errors/:code src/routes/error-preview.tsx Hidden error-page preview (not in the nav)

src/App.tsx declares them. The website uses real paths (BrowserRouter); the Tauri apps use hash routes (HashRouter) on their custom protocol (src/components/app-router.tsx). The Worker serves the app shell with 200 for known routes, 404 for anything else and a 301 for renamed routes (/deleted → /removed), so worker/spa.ts must be kept in sync with App.tsx. Every route except /, /games and the Not Found page is React.lazy.

With the verification gate on, a visitor who has not passed the Turnstile check gets the verification page instead of the shell on every app route (and 403 on /img); see worker/gate.ts and the setup in docs/operations.md (section 1, step 14).

Admin (/admin/)

Maintainer only. Cloudflare Access (the "Admin" application) guards /admin and /api/admin/*, and the Worker re-verifies the Access JWT and the ADMIN_EMAILS allow-list on every request (worker/access.ts, worker/admin.ts). The app shell is only served after that check. Pages (hash routes):

  • Review queue: approve (with override for removed games) or reject, in batches of 200.
  • Add games: paste any text or load a file, or read an itch.io collection; Check shows what Add would do with each URL before anything is written; Add queues the list in batches of 200 and then follows each game through the ingest (added / waiting / dropped and why, from scripts/state/ingest_outcomes.json).
  • Catalog: search, edit one game, or select up to 100 for a bulk edit (nsfw / safe_virus / notes) or a removal with a public reason (one commit); remove by list; restore removed games.
  • New games (added in the last 7 / 30 days, to review 18+ and virus checks in bulk), Activity (the D1 audit log) and Settings (auto-approve rules, followed itch.io collections, the last automatic run).

Writes go to the repo as a GitHub App (GraphQL createCommitOnBranch, so commits are "Verified"; worker/github.ts, worker/repo.ts). Approving a link commits it to scripts/temp_link.json, which starts the update.yml ingest workflow. The Maintainer's email is kept only in the D1 audit log, never in commits.

Worker

Existing static files (the app, /data/pack/*) are served by the assets layer without running the Worker. It runs for wrangler.jsonc assets.run_worker_first (/, /img/*, /api/*, /admin, /admin/*, and the five readable catalog files under /data) and for every request that matches no file.

Path File Purpose
/img/<160|640>/<path> worker/img.ts Resized WebP covers, stored in R2; only thumbnails that are in the catalog (/data/urls.json), upstream fixed to img.itch.zone
/api/health worker/index.ts Health check
/api/suggest worker/suggest.ts Suggest form: same-origin POST, per-IP rate limit, Turnstile, canonical itch.io URL, note ≤ 500 chars
/api/admin/* worker/admin.ts Admin API (queue, check, add, track, edit and remove one or up to 100 games, restore, activity, settings, itch.io collections)
/admin, /admin/* worker/admin.ts Admin app shell, after the Access check
/data/*.json (not /data/pack/) worker/legacy-data.ts The readable catalog JSON, passed only to apps 4.0–4.1.1 (Tauri Origin); everyone else gets 410 + the repository links
anything else worker/spa.ts App shell for routes, real 404 for missing files (a missing pack too: no-store)

Cron (23 */4 * * *, worker/index.ts), four steps that fail independently: discover.ts polls one itch.io RSS feed into the review queue; queue bookkeeping settles queued rows with the pipeline's ingest outcomes (queued → ingested / failed); automation.ts applies the Maintainer's automatic rules (auto-approve of unflagged items after the waiting time, new free games of followed collections, read with collections.ts) in one commit; then retention (Suggest notes after 180 days).

Bindings: ASSETS, THUMBS (R2 freeitchgames-thumbs), DB (D1 freeitchgames), RL_SUGGEST / RL_GATE (rate limits). Vars: SITE_ORIGIN, GITHUB_REPO, BOT_UA, GH_APP_ID, GH_APP_INSTALLATION_ID, ACCESS_TEAM_DOMAIN, ACCESS_AUD_ADMIN, TURNSTILE_SITEKEY. Secrets: GH_APP_PRIVATE_KEY, ADMIN_EMAILS, TURNSTILE_SECRET (DEV_ADMIN_EMAIL is for local runs only). Logs: Workers Observability, 10% head sampling.

canonical.ts and catalog.ts are ports of scripts/canonical.py and scripts/data_store.py + json_io.py; both sides are tested against tests/fixtures/url_vectors.json and tests/fixtures/golden/, so the Worker writes the same bytes as the pipeline.

Catalog data

vite-plugins/catalog-data.ts reads ../data_game/ and ../scripts/deleted_games.json at build time and emits:

  • dist/data/pack/ — what the site and the apps read. manifest-v1.json names, per chunk, a main pack (every field but description) and a desc pack, plus the removal-log and history packs. A pack is the records stored by column (dictionaries for repeated strings and every tag-like list; src/lib/data/pack-format.ts, shared with the plugin), deflated at level 9 and named <sha256 prefix>.bin: a name changes exactly when the bytes do, so packs are served immutable and a returning visitor fetches only the ones that changed. About 264 KB on a first visit for ~3,100 games (descriptions, ~170 KB, load on demand).
  • The readable JSON, byte-for-byte as before (index.json, game_info_NNN.json, count_history.json, deleted_games.json) and urls.json: the Worker reads urls.json and deleted_games.json through env.ASSETS, and passes the files to apps 4.0–4.1.1 only.
  • sitemap.xml.

The build fails on invalid JSON or an index/chunk mismatch, so a broken data commit never replaces a working deployment. Nothing from the catalog may reach the JS bundle (a data-only rebuild keeps the JS byte-identical). In dev, a middleware serves the same files (rebuilt when a source file changes).

  • Web: reads same-origin /data/pack/*; covers go through /img, so the visitor's browser never contacts itch.io until they click a link.
  • Tauri apps: read https://freeitchgames.win/data/pack/* (served with Access-Control-Allow-Origin: *) and load covers straight from img.itch.zone (src/lib/config.ts, src/lib/thumbnail.ts).

Loading (src/lib/data/catalog.ts): the manifest is revalidated on every load (cache: 'no-cache', shared for 10 s by the catalog, removal-log and history queries); packs use the normal HTTP cache. A 404 on a main pack means the manifest predates a deploy: it is fetched again (cache: 'reload') and the load retried once. Packs are inflated with DecompressionStream, or with fflate (a lazy chunk) where the browser lacks it (src/lib/data/compression.ts). Descriptions (src/hooks/useDescriptions.ts) are queries ['desc', <file>]: a game page loads its chunk's, a search all of them. They match their games by row, so only the desc file named in the same catalog is ever loaded; a 404 reloads the catalog instead.

The public catalog queries (db, deleted, count-history, and the desc packs the current catalog names) are persisted to IndexedDB (webapp.query-cache, up to 7 days) by a small binary persister (src/lib/data/persister.ts): one byte of format, then the deflated JSON, so DevTools shows bytes, not readable data. Writes are throttled (1 s) and skipped when no data object changed. gcTime must stay ≥ the persist maxAge, or restored queries are garbage-collected right after hydration; bump the data-vN part of CACHE_BUSTER in src/main.tsx when the cached shape changes.

Code splitting and targets

vite.config.ts codeSplitting.groups makes vendor-react, vendor-query (TanStack) and vendor-ui (Radix, lucide-react, class helpers). There is deliberately no charts group: Recharts is only reached from the lazy chart tabs, and a group would pull it into the first load. The chart tabs (src/components/charts/tabs/*) import chart components directly (no barrel file), so each tab stays in its own chunk.

Build targets: the website targets Safari / iOS 15.4 and Chrome / Edge 111+, Firefox 114+ explicitly; the Tauri build keeps Vite's default (baseline-widely-available, Safari 16.4+).

Source layout

Path Purpose
src/routes/*.tsx One file per route
src/components/site/* Header (top nav, global search with / shortcut, display menu, phone menu) and footer
src/components/games/* Games page pieces: filter chips and menus, the desktop table / phone list, the pager
src/components/charts/* One file per chart; tabs/* are the lazy tab chunks
src/components/ui/* shadcn/ui primitives
src/components/legal-gate.tsx First-visit click-to-accept gate (LEGAL_VERSION in src/stores/prefs.ts)
src/components/ext-link.tsx Runtime-aware external link (web vs Tauri)
src/lib/data/*, src/lib/config.ts Pack format, loader, compression, the binary IndexedDB persister; the pack base URL
src/lib/thumbnail.ts Cover URLs: /img on the web, img.itch.zone in the apps
src/lib/game-filters.ts, src/lib/format.ts, src/lib/platforms.ts The Games query (URL ⇄ filters, sorting, facet counts), locale-aware numbers and dates, platform labels
src/lib/turnstile.ts Loads Turnstile on demand (Suggest page only)
src/lib/i18n/* Typed i18n: en.ts is the source of truth; vi.ts is only ever lazy-imported
src/lib/runtime.ts, src/lib/external-link.ts isTauri(); openExternal() (opener plugin in the apps, window.open on the web)
src/lib/legacy.ts One-time cleanup of v3 storage and routes
src/lib/about.ts App / social / third-party constants for the About page
src/stores/* Zustand: prefs (webapp.prefs), theme (webapp.theme)
src/hooks/* Data hooks (catalog, lazy descriptions), SEO head, theme / density / scrollbar effects, Android back button

Deploy (web)

Cloudflare Workers Builds builds and deploys every push to main (no GitHub Actions deploy). Dashboard settings for the Worker free-games-itchio-list: root directory webapp, build command npm run build, deploy command npx wrangler deploy. assets.directory must stay ./dist — never a source directory.

  • D1 migrations are applied by hand, never by the build: npx wrangler d1 migrations apply freeitchgames --remote (before deploying code that needs them).
  • Secrets: npx wrangler secret put <NAME>.
  • Staging: npx wrangler deploy --env staging → staging.freeitchgames.win, the whole host behind Access, its own R2 bucket and D1 database, no cron.

The old GitHub Pages address (https://poli0981.github.io/free-games-itchio-list/) only redirects to https://freeitchgames.win.

Desktop and Android (Tauri)

See TAURI.md: prerequisites, npm run tauri:dev / npm run tauri:build, the Android APK build and signing, and adding Rust commands. Installers and the APK are built by release_desktop.yml and release_android.yml on a v* tag.

House rules

  • Don't commit dist/, .wrangler/, .dev.vars, src-tauri/target/, src-tauri/gen/ or src-tauri/icon-source.png.
  • Never commit a secret (GitHub App key, Turnstile secret, Access tokens, Android keystore). Production secrets live only in Cloudflare (wrangler secret put) and GitHub Actions secrets.
  • New npm dep? Add it to src/lib/about.ts THIRD_PARTY so the About page lists it.
  • New external link? Use <ExtLink href="…"> from src/components/ext-link.tsx, never a raw <a href="…" target="_blank">. Plain anchors work on the web but silently break in the Tauri apps.
  • New route? Add it to src/App.tsx and worker/spa.ts; if it should be indexed, also to src/hooks/useSeoHead.ts and STATIC_PAGES in vite-plugins/catalog-data.ts (sitemap).