Files
free-games-itchio-list/webapp/TAURI.md
T
poli0981andClaude Opus 5.5 a3bfe04b40 Compact catalog packs, binary cache, themed scrollbars; bump to 4.2.0 (#103) [skip-discuss]
- Catalog packs: the build emits /data/pack/manifest-v1.json plus
  content-hashed deflate-raw packs (columns + dictionaries); the site and
  the apps read them (about 264 KB on a first visit instead of about 520 KB
  of JSON). Descriptions live in their own packs and load on demand (a game
  page: its chunk; a search: all of them).
- The IndexedDB cache is stored as compressed bytes by a small binary
  persister (replaces @tanstack/query-async-storage-persister); fflate is
  the lazy fallback where the browser has no Compression Streams.
- The readable /data/*.json goes only to apps 4.0-4.1.1 (Tauri Origin);
  everyone else gets a 410 with links to the repository
  (worker/legacy-data.ts, five positive run_worker_first entries).
- /img: exact width strings only, fallback originals and missing images
  kept at the edge for a day, failed background puts are logged.
- Themed scrollbars and a "Hide scrollbars" setting (Settings and the
  display menu); chart cards no longer block their list scrollbars.
- Policies (LEGAL_VERSION 2026-10-03): data reuse goes through the
  repository. Docs, changelog and version 4.2.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 19:19:42 +07:00

13 KiB
Raw Blame History

Tauri desktop & Android apps

The desktop apps (Windows / macOS / Linux) and the sideloadable Android .apk are Tauri 2 builds of the same React app as the website https://freeitchgames.win. Desktop instructions come first; the Android section is at the bottom.

What the apps are

Read-only viewers of the public catalog: no sign-in, no editing, no telemetry.

  • Catalog data is downloaded from https://freeitchgames.win/data/pack (manifest-v1.json
    • compact .bin packs, served with Access-Control-Allow-Origin: *; descriptions load on demand). The Tauri build does not bundle the catalog (vite.config.ts only adds the catalogData plugin to the web build), so the apps always show the current catalog. The last downloaded copy is cached, compressed, in IndexedDB for up to 7 days. Apps 4.0–4.1.1 read the older readable JSON under /data, which the Worker serves only to the apps' webview origins (tauri://localhost, http(s)://tauri.localhost; worker/legacy-data.ts).
  • Cover images load directly from itch.io's image CDN (img.itch.zone). The website's /img proxy is not used by the apps (src/lib/thumbnail.ts).
  • Links open in the system browser through tauri-plugin-opener (capability scope: https://* only, src-tauri/capabilities/default.json).
  • Suggest is a web-only form: in the apps the /suggest page links to https://freeitchgames.win/suggest. The admin app is not part of the Tauri build.
  • Routing uses hash routes (HashRouter) on Tauri's custom protocol, and Vite builds with a relative base (./). The website uses real paths.
  • CSP (app.security.csp in src-tauri/tauri.conf.json) limits connect-src to the app itself, Tauri IPC and https://freeitchgames.win, and img-src to the app, data: URLs and https://img.itch.zone.
  • Updates are manual: download a new release from GitHub Releases.

Runtime requirements (end users)

The apps' JavaScript targets Vite's default baseline-widely-available (Chrome / Edge 111+, Firefox 114+, Safari 16.4+).

  • Windows: Microsoft Edge WebView2 (built into Windows 11; on Windows 10 install it from https://developer.microsoft.com/microsoft-edge/webview2/).
  • macOS: Safari / WebKit 16.4 or newer (the app uses the system WebKit).
  • Linux: WebKitGTK 4.1 (release builds are made on Ubuntu 22.04 to keep the glibc floor low).
  • Android: Android 11+ on arm64-v8a (see below).
  • An internet connection to download the catalog and covers.

Local prerequisites (building)

  1. Rust toolchain (stable). Install via https://rustup.rs.
  2. Node.js + npm as for the web app (see README.md).
  3. Platform deps:
    • Windows: WebView2 (see above).
    • macOS: Xcode Command Line Tools (xcode-select --install).
    • Linux (Debian/Ubuntu):
      sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
      

Run dev mode

cd webapp
npm ci
npm run tauri:dev

This runs npm run dev (Vite on port 5173, beforeDevCommand) and opens a native window pointing at it; HMR works as in web dev. The dev app, like the release app, reads the catalog from the live site, so it needs internet access, and a change to the pack format works there only once the site that serves it is deployed. The Worker (wrangler dev) is not needed.

Build native installers

cd webapp
npm run tauri:build

beforeBuildCommand runs npm run build (Tauri mode: public app only, no bundled /data) into webapp/dist/, which Tauri packages. Outputs:

  • Windows: webapp/src-tauri/target/release/bundle/msi/*.msi and nsis/*.exe
  • macOS: webapp/src-tauri/target/release/bundle/dmg/*.dmg and macos/*.app
  • Linux: webapp/src-tauri/target/release/bundle/{appimage,deb,rpm}/*

Installer license page

bundle.licenseFile points to src-tauri/installer/EULA.rtf, shown by the Windows installers. It must be RTF: WiX (.msi) requires it and NSIS (.exe) accepts it. (bundle.windows.nsis.license does not exist in the pinned @tauri-apps/cli and fails config validation on every platform.) Keep it in sync with docs/EULA.md, which covers only the desktop and Android apps.

CI builds

.github/workflows/release_desktop.yml runs on a v* tag push (or workflow_dispatch). Its create-release job opens one draft GitHub Release; the build jobs (Windows, macOS aarch64 + x86_64 cross-compiled from an Apple Silicon runner, Linux) upload into it: .msi / .exe, .dmg / .app.tar.gz / .pkg (built with pkgbuild, identifier read from tauri.conf.json), .deb / .rpm / .AppImage. Release builds use no npm / cargo caches. The Android job (below) attaches the APK to the same draft; the Maintainer publishes it once every asset is there (release steps: CLAUDE.md).

Before tagging, keep the version equal in webapp/src-tauri/tauri.conf.json, webapp/src-tauri/Cargo.toml (+ Cargo.lock), webapp/package.json and webapp/src/lib/about.ts (APP.version). The bundlers read tauri.conf.json, and the Android versionCode is derived from it.

Detecting Tauri at runtime

import { isTauri } from '@/lib/runtime'

if (isTauri()) {
  // running inside the desktop or Android shell
}

The app uses it for the data URL, cover URLs, external links, the router, the Suggest page and the app-only EULA link in the legal gate (which has no "Leave" button in the apps). The footer shows a small "Desktop app (Tauri)" / "Mobile app (Tauri)" badge (picked by isAndroid()), and on Android the back button walks the router history (src/hooks/useBackButton.ts).

Adding new Rust commands

src-tauri/src/lib.rs exposes runtime_info. To add another:

#[tauri::command]
fn my_thing(arg: String) -> String { ... }

// inside run():
.invoke_handler(tauri::generate_handler![runtime_info, my_thing])

Then call it from the frontend:

const { invoke } = await import('@tauri-apps/api/core')
await invoke<string>('my_thing', { arg: 'hello' })

If a command needs a new permission, add it to src-tauri/capabilities/default.json with the narrowest scope.

Android APK

Same React build, wrapped in an Android WebView via Tauri mobile, shipped as a sideloadable .apk (no Play Store) on the GitHub Releases page. The Rust side is mobile-ready (#[cfg_attr(mobile, tauri::mobile_entry_point)] in lib.rs, cdylib crate type, single-instance plugin gated to desktop).

Prerequisites

  • Android Studio + SDK + NDK + command-line tools.
  • JDK 17 or 21 for the Gradle build — Android Studio's bundled JBR is ideal. The Android Gradle Plugin does not support JDK 26, so if a newer JDK is your system default, point JAVA_HOME at a 17/21 JDK (or the JBR) for the android build step. CI uses Temurin 17.
  • Env vars (Windows example — adjust paths):
    setx JAVA_HOME    "C:\Program Files\Android\Android Studio\jbr"   # JDK 17/21 — NOT 26
    setx ANDROID_HOME "$env:LOCALAPPDATA\Android\Sdk"
    setx NDK_HOME     "$env:LOCALAPPDATA\Android\Sdk\ndk\<version>"   # ls $ANDROID_HOME\ndk
    
    CI pins the NDK version in release_android.yml (NDK_VERSION); point NDK_HOME at the same version locally, otherwise Tauri picks the highest installed NDK.
  • Rust Android targets:
    rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
    

Init / dev / build

cd webapp
npm run tauri -- android init                                # generates src-tauri/gen/android (gitignored)
npm run tauri -- android dev                                 # live-reload on a connected device/emulator
npm run tauri -- android build --apk --debug --target aarch64  # debug APK you can install by hand
npm run tauri -- android build --apk --target aarch64        # release (unsigned) APK, arm64-v8a only

We ship arm64-v8a only (every phone since ~2017; smaller download). minSdkVersion is 30 (Android 11), set in tauri.conf.json bundle.android. versionName/versionCode derive from the tauri.conf.json version (versionCode = major*1e6 + minor*1e3 + patch).

Why Android 11 (API 30)?

The floor was 24 (Android 7.0) through v3.8.0; v3.9.0 raised it to 30. The reasoning, stated honestly so it's defensible:

  • It's not a JS-feature floor. The Android System WebView is independently updatable from the Play Store down to API 24, so IndexedDB and the modern JavaScript the app needs work fine on older OSes too. That is not the binding constraint.
  • Security + patch availability is the constraint. Android 11 brought scoped-storage enforcement, one-time and auto-reset permissions, and a tighter sandbox. Older releases are also off Google's AOSP monthly Security Bulletins (Android 10 ended 2023-03-06, Android 11 itself ended 2024-02-05; only Android 14/15/16 are still on the bulletins as of mid-2026).
  • Tested range is the other constraint. We only validate on Android 11+ (see docs/pc_spec.md); shipping a floor we haven't tested is the real risk.
  • Reach cost is small. API 30+ ≈ 86.9% of active devices (was 96.6% at API 24) — we drop only the pre-2020 long tail.

minSdkVersion is also the install block: Android's package installer refuses an APK whose minSdkVersion exceeds the device's API level ("app not installed / incompatible"), so there's no runtime version check by design.

Data sources: endoflife.date/android, Android Security Bulletins, StatCounter version share, apilevels.com (StatCounter cumulative distribution).

Tested on: emulator Android 11 → latest; real phone vivo 1907 / Android 12.

Signing for distribution

src-tauri/gen/android is gitignored and regenerated by android init, so we do not edit the generated Gradle. Instead, build an unsigned APK and sign it afterwards with zipalign + apksigner (the CI workflow does exactly this). Release APKs are signed with the project's key; users should only install the APK from the GitHub Releases page.

# one-time: create a release keystore (keep the .jks out of git, never lose it)
keytool -genkey -v -keystore release.jks -storetype JKS \
  -keyalg RSA -keysize 2048 -validity 10000 -alias itchio-release

# after `android build --apk`:
BT="$ANDROID_HOME/build-tools/<ver>"
UNSIGNED=$(find src-tauri/gen/android/app/build/outputs/apk -name "*-release-unsigned.apk" | head -1)
"$BT/zipalign" -v -p 4 "$UNSIGNED" aligned.apk          # zipalign BEFORE apksigner
"$BT/apksigner" sign --ks release.jks --ks-key-alias itchio-release \
  --out FreeGamesItchio.apk aligned.apk
"$BT/apksigner" verify --verbose FreeGamesItchio.apk

*.jks and *.keystore are gitignored.

CI

.github/workflows/release_android.yml builds + signs on a v* tag and attaches the APK to the same draft Release as the desktop installers (manual workflow_dispatch instead uploads it as a downloadable workflow artifact for device testing). Required repo secrets:

  • ANDROID_KEYSTORE_BASE64 — base64 of release.jks
  • ANDROID_KEYSTORE_PASSWORD
  • ANDROID_KEY_ALIAS (itchio-release)

The JDK setup must not use cache: gradle: gen/android is generated mid-job, so there are no Gradle files at checkout to key the cache on (the step hard-fails). Like the desktop job, the Android release build uses no dependency caches at all (a poisoned cache could end up in a signed release).

Gotchas (each cost a release if relearned)

  1. Identifier must be hyphen- AND underscore-free. Android rejects hyphens in the package id (android init panics); Tauri's config validator rejects underscores. The only string valid on both is alphanumeric — ours is com.poli0981.freegamesitchio.
  2. zipalign BEFORE apksigner. Re-aligning a signed APK invalidates the signature.
  3. gen/android is gitignored — signing is a post-build step, not a Gradle edit, so it survives regeneration. Don't commit gen/.
  4. Pin the NDK in CI to match local. A floating NDK is a "works locally, breaks in CI."
  5. Keep the signing key forever. Lose it and users can't upgrade an installed APK in place (Android requires a stable signing identity).