# 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`](../../.github/workflows/release-desktop.yml) and [`.github/workflows/release-android.yml`](../../.github/workflows/release-android.yml). ## Prerequisites | Tool | Version | Install | | ---------- | ------------------- | ----------------------------------------------------------- | | Node.js | 26 (LTS), as in `web/.node-version` | | | Rust | stable (via rustup) | | | 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](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) if missing). **macOS** — Xcode Command Line Tools: ```bash xcode-select --install ``` **Linux (Ubuntu/Debian)** — same packages CI installs: ```bash 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 ```bash 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 ```bash 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`](tauri.conf.json). - Private key + (optional) password live in repo Secrets: - `TAURI_SIGNING_PRIVATE_KEY` - `TAURI_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_dispatch` with 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/`](gen/android) (generated once with `tauri android init`); the build artefacts inside it are gitignored. CI: [`.github/workflows/release-android.yml`](../../.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): ```powershell $env:ANDROID_HOME = "$env:LOCALAPPDATA\Android\Sdk" $env:NDK_HOME = "$env:ANDROID_HOME\ndk\" $env:JAVA_HOME = "\jbr" ``` ### Build ```bash 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`](../../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: ```bash 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 = 30` in [`gen/android/app/build.gradle.kts`](gen/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`](../../docs/android-support.md). Don't re-run `tauri android init` — it would reset this. - **No auto-updater on Android** — `tauri-plugin-updater` is 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). Move `CARGO_HOME` to the project's drive, or set `kotlin.incremental=false` in `gen/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-rs` build fails** — verify Rust toolchain is `stable` and `rustup target list --installed` includes the host triple. - **macOS universal binary** — ensure both `aarch64-apple-darwin` and `x86_64-apple-darwin` targets are added (`rustup target add ...`). CI does this in the `dtolnay/rust-toolchain` step. - **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/desktop` shows 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 `` carries `referrerpolicy="no-referrer"` from 2.0.1 on (`src/lib/images.test.ts` enforces it); 2.0.0 itself relies on a Configuration Rule on the zone. Security → Events names the block. See `docs/SECURITY_SETUP.md` section 10. ## Known advisories - **`glib` (GHSA-wrw7-89jp-8q8g, medium, Linux-only)** — accepted, no upstream fix available. The gtk-rs binding stack is pinned at `glib 0.18` by the latest `webkit2gtk` crate (2.0.2, which requires `glib ^0.18`) and by `tao`/`wry` (`gtk ^0.18`). The patched `glib 0.20` needs 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 when `tauri`/`wry`/`webkit2gtk` adopt gtk-rs 0.20, then `cargo update` and re-enable the alert. ## Related - [`../../docs/dev_env.md`](../../docs/dev_env.md) — IDE + toolchain - [`../../docs/pc_spec.md`](../../docs/pc_spec.md) — maintainer hardware spec - [`../../.github/workflows/release-desktop.yml`](../../.github/workflows/release-desktop.yml) — CI build pipeline - [Tauri 2 docs](https://v2.tauri.app/) — upstream