Files
free-games-itchio-list/docs/dev_env.md
T
poli0981andClaude Fable 5.2 0e0e442de5 chore: maintenance mode, Qodana analysis; 4.6.1 (#188) [skip-discuss]
The project moves to maintenance mode (stable, feature-complete): docs, templates and badges (EN + VI). Qodana analysis in CI for the TypeScript / JavaScript, Python and Rust projects, with the findings of its first reports fixed. Version 4.6.1.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-11 21:44:32 +07:00

11 KiB

Development environment

Tooling the Maintainer uses to write and test code in this repo, and how to run each part locally. You don't need exactly the same setup to contribute — anything compatible with the required toolchains works. This is for reproducibility.

IDEs

JetBrains 2026.x (paid lineup):

  • PyCharm — Python pipeline (scripts/, bash/ wrappers).
  • WebStorm — webapp/ (React + TypeScript + Vite, the Cloudflare Worker).
  • RustRover — webapp/src-tauri/ (Tauri 2 native shell).

VS Code, Sublime, vim, etc. all work fine; nothing JetBrains-specific is checked into the repo.

TypeScript 7 (the tsc that npm run build runs) is a native binary without tsserver. In VS Code, install the TypeScript Native Preview extension (TypeScriptTeam.native-preview) for the TS 7 language server. In WebStorm, use its TypeScript 7 support or point Languages & Frameworks → TypeScript at webapp/node_modules/@typescript/old (TypeScript 6.0, which reports the same errors).

Language toolchains

Stack Required Used for
Python 3.15 (.github/python-version) Data pipeline (scripts/) and its tests
Node.js 26+ (CI uses webapp/.node-version) Web app, admin app, Worker, Tauri front end
npm ships with Node.js Dependencies (npm ci from package-lock.json)
Wrangler project dependency (npx wrangler) Local Worker, local D1, deploys
Rust stable (via rustup) Tauri desktop / Android builds only
Git recent Repo history, signed commits and tags

Android builds also need Android Studio, the SDK / NDK and JDK 17 or 21 — see webapp/TAURI.md.

Python pipeline

Setup

python -m venv .venv
# activate it: .venv\Scripts\activate (Windows) · source .venv/bin/activate (macOS / Linux)
pip install -r requirements-dev.txt

Python 3.15 reads and writes files as UTF-8 by default (UTF-8 mode, PEP 686), so Windows no longer needs PYTHONUTF8=1.

Both requirements files pin every package with its hashes; pip checks them on install. To add or change a dependency, edit requirements.in or requirements-dev.in and recompile the lock with pip-tools — the command is at the top of each .in file (run it on Python 3.14, which Dependabot can read; CLAUDE.md, gotcha 40).

Checks (same as python-ci.yml)

pytest                                   # tests/ — network access is blocked (tests/conftest.py)
ruff check scripts tests webapp/scripts  # lint (config in the root pyproject.toml)
ruff format --check scripts tests        # formatting (drop --check to apply it)
vulture                                  # dead code
python scripts/validate.py               # checks every catalog data file

pytest --cov --cov-report=xml also measures coverage and writes coverage.xml, as the SonarQube Cloud workflow (sonarcloud.yml) does.

Try a real scrape

These make real requests to itch.io:

# add a game URL to scripts/temp_link.json, then:
python scripts/update_info.py --out patch.json
python scripts/apply_patch.py patch.json

# or re-check a few games already in the catalog:
python scripts/refresh.py --out patch.json --budget 5
python scripts/apply_patch.py patch.json

Scanners never write the catalog: they emit a URL-keyed patch, and apply_patch.py applies it and runs validate.py. A local run changes data_game/, scripts/*.json and scripts/state/ in your working tree — leave those changes out of code PRs; on main the pipeline workflows update the catalog. See CLAUDE.md for the data-layer overview.

Web app

cd webapp
npm ci
npm run dev          # public app on http://localhost:5173 with HMR; /data (packs + JSON) is built from ../data_game
npm run build        # tsc -b + vite build → webapp/dist/ (app, /admin/, /data/pack + legacy JSON, sitemap.xml)
npm run preview      # serve the production build (without the Worker)

Covers (/img), the Suggest form (/api/suggest) and the admin API are Worker routes. Vite proxies /api and /img to the Worker on port 8787, so start it too (next section); without it the rest of the app works but covers don't load.

Worker (local)

In a second terminal:

cd webapp
npm run build                                            # the Worker serves dist/ as its static assets
npx wrangler d1 migrations apply freeitchgames --local   # creates the local review-queue database
npx wrangler dev                                         # http://localhost:8787 (same as npm run cf:dev)

Keep using http://localhost:5173 for the app; http://localhost:8787 serves the last build, so rebuild when you want it to show your changes. Everything runs locally (workerd); local D1, R2 and cache data live in webapp/.wrangler/ (gitignored — delete it to start over). Run the migrations command again after adding a file to worker/migrations/ (never edit a migration that has been applied).

.dev.vars

Local settings go in webapp/.dev.vars (dotenv format, gitignored). Values there also override the vars in wrangler.jsonc for local runs. A typical file:

DEV_ADMIN_EMAIL=you@example.com
SITE_ORIGIN=http://localhost:5173
TURNSTILE_SITEKEY=1x00000000000000000000AA
TURNSTILE_SECRET=1x0000000000000000000000000000000AA
# Only to try the verification gate under `npx wrangler dev` (http://localhost:8787):
# GATE_SECRET=<32+ random characters, e.g. `openssl rand -hex 32`>
Key Kind What it does
DEV_ADMIN_EMAIL local only, optional Lets you into the admin without Cloudflare Access. Honoured only when the host is localhost, 127.0.0.1 or [::1]; ignored everywhere else
ADMIN_EMAILS secret Comma-separated admin allow-list, checked behind Access. Not needed locally with DEV_ADMIN_EMAIL
TURNSTILE_SECRET secret Suggest form and verification gate, together with the TURNSTILE_SITEKEY var
GATE_SECRET secret Signs the verification-gate cookie (32+ characters). Without it the gate stays off. Locally, set SITE_ORIGIN=http://localhost:8787 and open the site through wrangler dev; the cookie is fig_gate there (no Secure)
GATE_BOT_TOKEN secret The value the zone's Transform Rule sends for verified bots (32+ characters). Required in production, not on localhost
GH_APP_PRIVATE_KEY secret GitHub App private key for admin writes — the PEM as GitHub downloads it (PKCS#1) or PKCS#8, together with the GH_APP_ID and GH_APP_INSTALLATION_ID vars
SITE_ORIGIN var override The Suggest form and the verification gate only accept POSTs whose Origin equals it

A feature whose settings are missing answers 503; the public site needs none of them. The two Turnstile values above are Cloudflare's always-pass test keys (Turnstile testing); never use them in production. npm run cf:types ignores .dev.vars (it reads the empty types.env), so local secrets never reach the committed worker-configuration.d.ts.

Suggest form

With the file above, the local D1 migrated and both servers running, http://localhost:5173/suggest submits into the local review queue.

Admin

With DEV_ADMIN_EMAIL set, open http://localhost:5173/admin/ (Vite, hot reload) or http://localhost:8787/admin/ (the built copy, as in production). Without the GitHub App settings the admin is read-only: actions that write to the repo answer 503. With GH_APP_ID, GH_APP_INSTALLATION_ID and GH_APP_PRIVATE_KEY set, approvals and edits become real commits to the GITHUB_REPO repository (by default the public one) — point GITHUB_REPO at a fork where your App is installed.

Cron (RSS discovery)

npx wrangler dev --test-scheduled
# then open http://localhost:8787/__scheduled

This runs scheduled() once: it polls one real itch.io RSS feed into the local queue, then does the queue bookkeeping. Use it sparingly.

Web app checks (same as webapp-ci.yml)

cd webapp
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 / dependencies
npm test                               # Vitest: app + Worker; D1 tests start a local workerd
npx tsc -b                             # type-check only (npm run build runs it too)
npm run build
npm run cf:check                       # wrangler deploy --dry-run: validates the Worker config, deploys nothing

npm run test:coverage runs the tests with v8 coverage and writes coverage/lcov.info, as the SonarQube Cloud workflow (sonarcloud.yml) does.

Qodana (JetBrains) also analyses the code in CI (qodana.yml: TypeScript / JavaScript, Python and Rust, each with its own qodana.yaml). It needs the project tokens, so it has no local command here; the same inspections are built into WebStorm, PyCharm and RustRover.

After editing wrangler.jsonc, run npm run cf:types and commit the regenerated worker-configuration.d.ts.

Desktop and Android apps (Tauri)

cd webapp
npm run tauri:dev    # native window + HMR
npm run tauri:build  # native installers

The apps read the live catalog packs from https://freeitchgames.win/data/pack and load covers from img.itch.zone, so they need internet access but not the local Worker (and code that changes the pack format only works in tauri:dev once the site with that format is deployed). Platform prerequisites (WebView2 on Windows 10, Xcode CLT on macOS, libwebkit2gtk-4.1-dev on Debian/Ubuntu) and the Android build are documented in webapp/TAURI.md.

Mobile testing

Web UI changes that touch responsive layout, navigation or the data table must be smoke-tested on a real iOS device before tagging a release; the Android APK is signed off on the Android devices. See pc_spec.md for the test devices.

Deploying (Maintainer)

Cloudflare Workers Builds deploys every push to main (root directory webapp, build npm run build, deploy npx wrangler deploy). D1 migrations are applied by hand (npx wrangler d1 migrations apply freeitchgames --remote), secrets are set with npx wrangler secret put <NAME>, and npx wrangler deploy --env staging deploys the staging Worker. Details: webapp/README.md.

Git hygiene

  • Tag releases from origin/main only (see the release process).
  • The Maintainer's commits and release tags are signed locally (commit.gpgsign=true, git tag -s).
  • Never commit webapp/dist/, webapp/.wrangler/, webapp/.dev.vars, webapp/src-tauri/target/, webapp/src-tauri/gen/, Android keystores, or any secret (GitHub App key, Turnstile secret, Access tokens). webapp/src-tauri/Cargo.lock is committed.

See also