- docs/plan/16-toolchain-2026.md: the assessment - what each release
changes, what was measured here, the decisions, how to move each runtime
next time, and what was left.
- docs/plan/17-typescript-7.1.md: the springboard for dropping TypeScript 6
once 7.1 ships - start conditions and how to check them, the steps, the
planted-error table and the baselines to compare against.
- CLAUDE.md: "TypeScript is two packages, on purpose" and "One version of
each runtime"; the uv compile line says 3.15.
- dev_env (EN/VI), README, AUTHORS, TAURI.md, web/README, THIRD_PARTY,
DEPLOYMENT (Workers Builds' NODE_VERSION=26, the Checks paragraph),
ACKNOWLEDGEMENTs and the About page's stack list ("TypeScript 7 + 6").
- CHANGELOG: the Tooling entry.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
10 KiB
Tauri 2 desktop + Android build
This file documents how to build and run the Tauri wrapper around the SvelteKit web app — both the desktop bundles and the sideloadable Android APK. CI builds use the same recipes via .github/workflows/release-desktop.yml and .github/workflows/release-android.yml.
Prerequisites
| Tool | Version | Install |
|---|---|---|
| Node.js | 26 (LTS), as in web/.node-version |
https://nodejs.org/ |
| Rust | stable (via rustup) | https://rustup.rs/ |
| npm | bundled with Node | comes with Node |
| Tauri CLI | 2.x | invoked via npx tauri or npm run tauri ... |
Platform-specific deps
Windows — nothing extra (Tauri 2 ships its own WebView2 detection; install WebView2 Runtime if missing).
macOS — Xcode Command Line Tools:
xcode-select --install
Linux (Ubuntu/Debian) — same packages CI installs:
sudo apt-get update
sudo apt-get install -y \
libwebkit2gtk-4.1-dev \
libappindicator3-dev \
librsvg2-dev \
patchelf \
libssl-dev \
build-essential \
curl wget file
Local dev
cd web
npm ci # install web deps once
npm run tauri dev # dev build with hot reload
This boots Vite (npm run dev) under the hood and wires Tauri to it. The window opens at 1280×860 and can be resized down to 880×600.
Production build
cd web
npm run tauri build
Output bundles land in web/src-tauri/target/release/bundle/:
| Platform | Artefact |
|---|---|
| Windows | .msi |
| macOS | .dmg (universal binary) |
| Linux | .AppImage, .deb |
Auto-update + signing
The desktop app checks for an update a few seconds after it starts, once per session, and offers to install it and restart. Updater clients reject unsigned binaries.
The update feed is https://free-steam-games.win/api/updates/desktop (plugins.updater.endpoints in tauri.conf.json), not a GitHub releases/latest URL. "Latest" on this repository is usually a dataset v* release, which has no latest.json, so that URL 404'd. The Worker route (web/worker/routes/updates.ts) reads the repository's releases feed, picks the highest published desktop-vX.Y.Z release, validates its latest.json and returns it, or answers 204 ("no update"). A draft release is therefore never offered: publish it after smoke-testing, and clients see it within about five minutes.
Updating keeps the app's settings. The webview's storage is cleared once, only when upgrading from a build older than 2.0 (needs_purge in src/lib.rs), to evict a service worker those builds registered.
- Public minisign key is baked into
tauri.conf.json. - Private key + (optional) password live in repo Secrets:
TAURI_SIGNING_PRIVATE_KEYTAURI_SIGNING_PRIVATE_KEY_PASSWORD
- The CI workflow injects them at build time. Local builds without these secrets still produce binaries, but updater clients won't trust them.
CI
.github/workflows/release-desktop.yml triggers on:
- Push of any
desktop-v*tag (e.g.desktop-v1.1.0) - Manual
workflow_dispatchwith a tag input
It runs the build matrix (Win / macOS-universal / Linux), uploads installers as draft Release assets, and emits latest.json for the auto-updater (includeUpdaterJson: true). It needs TAURI_SIGNING_PRIVATE_KEY, because createUpdaterArtifacts signs every bundle.
Android build
The same web app packages as a sideloadable Android APK via Tauri 2 mobile. The Gradle project is committed under gen/android/ (generated once with tauri android init); the build artefacts inside it are gitignored. CI: .github/workflows/release-android.yml.
Prerequisites (in addition to Node + Rust above)
| Tool | Notes |
|---|---|
| Android Studio | Brings the SDK + a bundled JDK (JBR). |
| Android SDK | Platform-Tools, Build-Tools, a recent Platform — Gradle auto-installs missing ones. |
| Android NDK | "Side by side"; any recent r26/r27/r30 works (built here with r30). |
| JDK | 17 recommended; the bundled JBR 21 also builds. |
| Rust targets | rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android |
Env vars (Windows example — set the NDK to the exact versioned folder):
$env:ANDROID_HOME = "$env:LOCALAPPDATA\Android\Sdk"
$env:NDK_HOME = "$env:ANDROID_HOME\ndk\<version>"
$env:JAVA_HOME = "<Android Studio>\jbr"
Build
cd web
npm run tauri:android:build # signed universal release APK (all ABIs)
npm run tauri:android:dev # run on emulator / connected device
npm run tauri -- android build --apk --debug --target aarch64 # fast debug build, single ABI
Output: gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk. Minimum Android 11 (API 30) — see docs/android-support.md for the requirement + rationale.
Signing
Release APKs sign from gen/android/keystore.properties (gitignored), pointing at a keystore you generate once:
keytool -genkeypair -v -keystore f2p-tracker-release.jks \
-alias f2p-tracker -keyalg RSA -keysize 2048 -validity 10000
keystore.properties has four lines: storeFile (absolute path, forward slashes), storePassword, keyAlias, keyPassword. Back up the keystore + passwords — every future update must reuse the same key, or users have to uninstall first. Without the file the release build stays unsigned (and won't install).
CI
release-android.yml triggers on android-v* tags (or manual dispatch), decodes the keystore from repo Secrets, builds a signed universal APK, and attaches it to a draft Release. Required Secrets:
ANDROID_KEYSTORE_BASE64—base64 -w0 f2p-tracker-release.jks(or PowerShell[Convert]::ToBase64String([IO.File]::ReadAllBytes("f2p-tracker-release.jks")))ANDROID_KEYSTORE_PASSWORD,ANDROID_KEY_ALIAS,ANDROID_KEY_PASSWORD
Notes
- Minimum Android 11 (API 30) —
minSdk = 30ingen/android/app/build.gradle.kts. Android's installer blocks the APK below that (INSTALL_FAILED_OLDER_SDK), so it's also the OS-level version gate — no in-app check needed. Floor chosen for security (Android 7–10 are EOL with no Google OS patches and old WebViews) over raw reach; tested on emulator 11→16 + a real vivo 1907 (Android 12). Full rationale + version stats:docs/android-support.md. Don't re-runtauri android init— it would reset this. - No auto-updater on Android —
tauri-plugin-updateris desktop-only. The app checks GitHub Releases once per session and offers the newer APK as a download; installing it over the top keeps your data (same signing key → no uninstall). - Edge-to-edge — targetSdk 36 forces it; the layout uses
env(safe-area-inset-*)to dodge the status / gesture-nav bars. - Kotlin cross-drive warning — if the Cargo registry (
C:) and the project (E:) are on different drives, Kotlin incremental compilation falls back to non-incremental every build (slower, harmless). MoveCARGO_HOMEto the project's drive, or setkotlin.incremental=falseingen/android/gradle.properties, to avoid it.
Troubleshooting
- WebKit missing on Linux — install
libwebkit2gtk-4.1-dev. The CI workflow's apt-install line is the canonical list. napi-rsbuild fails — verify Rust toolchain isstableandrustup target list --installedincludes the host triple.- macOS universal binary — ensure both
aarch64-apple-darwinandx86_64-apple-darwintargets are added (rustup target add ...). CI does this in thedtolnay/rust-toolchainstep. - Updater silent on sideloaded copies — sideloaded installs have a different bundle identifier; only the official MSI/DMG/AppImage receive update prompts.
- No update offered after a release — the release is still a draft (drafts are never offered), or the tag is not a strict
desktop-vX.Y.Z.curl -i https://free-steam-games.win/api/updates/desktopshows what clients see. - Game artwork blank, catalogue fine — Cloudflare Hotlink Protection refusing
/img/*because the webview sent its own origin (http://tauri.localhost/) as the Referer. Every<img>carriesreferrerpolicy="no-referrer"from 2.0.1 on (src/lib/images.test.tsenforces it); 2.0.0 itself relies on a Configuration Rule on the zone. Security → Events names the block. Seedocs/SECURITY_SETUP.mdsection 10.
Known advisories
glib(GHSA-wrw7-89jp-8q8g, medium, Linux-only) — accepted, no upstream fix available. The gtk-rs binding stack is pinned atglib 0.18by the latestwebkit2gtkcrate (2.0.2, which requiresglib ^0.18) and bytao/wry(gtk ^0.18). The patchedglib 0.20needs a gtk-rs 0.20 stack that no released Tauri 2.x ships, and Tauri 3 is not out yet. Only the Linux build links glib (Windows uses WebView2, macOS uses Cocoa), and the app does not exercise the affected API, so the Dependabot alert is dismissed as tolerable risk. Re-check whentauri/wry/webkit2gtkadopt gtk-rs 0.20, thencargo updateand re-enable the alert.
Related
../../docs/dev_env.md— IDE + toolchain../../docs/pc_spec.md— maintainer hardware spec../../.github/workflows/release-desktop.yml— CI build pipeline- Tauri 2 docs — upstream