The v1.7.2 global link interceptor routed external URLs through `@tauri-apps/plugin-shell`'s `open()`, but that throws on Android: "Scoped shell IO error: No such file or directory (os error 2)" — the shell plugin has no native URL handler on mobile, so every tapped link did nothing. (The earlier ConsentGate per-link shell.open from #98 had the same flaw; it was simply never tap-tested on Android.) Switch to `@tauri-apps/plugin-opener`'s `openUrl()`, whose `open_url` has a real cfg(mobile) split that routes to the native Intent.ACTION_VIEW handler. Plain `openUrl(url)` — no inAppBrowser (that option regressed os-error-2 on Android 16, plugins-workspace#2913). Wiring: tauri-plugin-opener crate + init, @tauri-apps/plugin-opener npm, "opener:default" capability (its allow-open-url permits any URL). Shell plugin removed entirely (openExternal was its only consumer) — also from vite optimizeDeps, knip ignore, and the THIRD-PARTY/TAURI-NOTES docs. Verified on emulator API 33 (Android 13, WebView Chromium 109): tapping the consent-gate License link and footer X link both fire ActivityManager START ACTION_VIEW and open Chrome; no shell error. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
9.1 KiB
Tauri runtime notes
Operational notes for the desktop builds. Aimed at maintainers, not end users.
Process lifecycle
src-tauri/src/lib.rs wires two cleanup hooks that should keep the host
process from outliving the main webview:
on_window_event— when the main window receivesCloseRequested, the app handle'sexit(0)is called explicitly. This guards against Windows builds occasionally leavingJSONPrism.exealive when the webview was the last live reference.RunEvent::ExitRequested— callsapp_handle.cleanup_before_exit()so any spawned shell children (none today, but the hook is in place) are signaled before the process exits.
If you ever add long-running spawned commands (e.g. via a shell/command plugin), remember to track their handles and kill them in the same hook.
WebView2 GDI leak (Windows, upstream)
Microsoft Edge WebView2 — the runtime Tauri uses on Windows — leaks GDI objects whenever the mouse hovers over the webview surface. Reported and acknowledged by Microsoft:
- WebView2Feedback #5536 — ~2000 GDI objects leaked per 30 seconds of mouse movement.
- Toggling visibility (
SetIsVisible) compounds the leak (~6000 obj/30s). - The per-process GDI cap is 10 000 by default; the app eventually fails to draw and crashes once exhausted.
This is not a JSONPrism bug. The fix has to come from the WebView2 runtime team. Until then:
- Watch the GDI object count in Task Manager (View → Select Columns) during long sessions. Above ~8000 means a restart is overdue.
- For QA / release smoke tests, open and close the app five times in
succession; verify no zombie
JSONPrism.exeremains in Task Manager.
Permissions / capabilities
See src-tauri/capabilities/default.json. Scope is intentionally narrow:
- Filesystem reads/writes only inside
$HOME,$DOCUMENT,$DOWNLOAD,$DESKTOP. - Dialog plugin for open/save.
- Opener plugin (
opener:default) for handing external URLs to the system browser —shell:openhas no native Android URL handler, so the opener plugin'sopenUrlis used instead.
Widening the scope requires both a capability edit and a CSP review in
tauri.conf.json.
Bundle targets
- Windows: MSI (via WiX) + NSIS
.exe. Tested on Windows 10 22H2 and Windows 11. - macOS: DMG +
.app, min version 12.0 (Monterey). - Linux: AppImage + Debian package.
The release matrix in .github/workflows/release.yml builds all four
combinations (Linux, macOS Intel, macOS Apple Silicon, Windows) on a v*
tag push.
Android (sideload APK)
JSONPrism ships an Android APK that users sideload. Minimum Android 12
(API 31) — set via bundle.android.minSdkVersion in tauri.conf.json; the
OS installer refuses older devices. The build target is a universal APK
(all ABIs in one file) so users only ever download one .apk.
Toolchain (local, Windows)
Environment variables Tauri's CLI reads:
JAVA_HOME→ Android Studio's JBR, e.g.C:\Jetbrains\Android Studio\jbrANDROID_HOME→C:\Users\<you>\AppData\Local\Android\SdkNDK_HOME→…\Android\Sdk\ndk\<version>
Rust targets: rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android. Verify with npm run tauri info.
NDK selection. The CLI auto-picks the highest NDK under
$ANDROID_HOME/ndk, regardless ofNDK_HOME. If you keep multiple NDKs and want a specific one, leave only that version installed. Builds are validated against NDK r27+; CI pinsndk;27.2.12479018.
The gen/android project
src-tauri/gen/android/ (the Gradle project from tauri android init) is
committed — source only. Its nested .gitignore files exclude build
outputs (build/, .gradle/, .cxx/, *.so, local.properties,
keystore.properties). Committing it keeps the signing edits in
app/build.gradle.kts and minSdkVersion stable, and makes CI reproducible.
You normally do not run tauri android init again. Only re-run it after a
major @tauri-apps/cli bump, and re-apply the signing block + verify
minSdk = 31 in app/build.gradle.kts afterward (the init overwrites it).
Launcher icons (res/mipmap-*/ic_launcher*.png) are generated by
npm run tauri:icon and gitignored, like the desktop icons — both the local
tauri:android:build script and CI regenerate them before building.
versionCode
bundle.android.versionCode in tauri.conf.json must increase monotonically
(needed for in-place upgrades). Derive it deterministically from semver:
versionCode = MAJOR*10000 + MINOR*100 + PATCH
e.g. 1.6.1 → 10601, 1.7.0 → 10700. Bump it together with version in
package.json / Cargo.toml / tauri.conf.json at release time.
Signing
Release signing is read from src-tauri/gen/android/keystore.properties
(gitignored), which points at a keystore .jks (also gitignored, kept outside
the repo). If the file is absent the release variant builds unsigned — fine
for contributors, but a release APK must be signed so it installs and so future
versions can upgrade in place.
Generate a keystore once:
& "$env:JAVA_HOME\bin\keytool.exe" -genkeypair -v `
-keystore "$env:USERPROFILE\jsonprism-upload-keystore.jks" -storetype JKS `
-keyalg RSA -keysize 2048 -validity 10000 -alias upload
Then create src-tauri/gen/android/keystore.properties:
storePassword=…
keyPassword=…
keyAlias=upload
storeFile=C:/Users/<you>/jsonprism-upload-keystore.jks
Use forward slashes in
storeFile—.propertiestreats\as an escape. Back up the.jksand its passwords (password manager). Losing the key means users can no longer upgrade in place — they'd have to uninstall first.
CI signing secrets
The android job in release.yml needs these repository secrets:
| Secret | Value |
|---|---|
ANDROID_KEYSTORE_BASE64 |
base64 of the .jks (required) |
ANDROID_KEYSTORE_PASSWORD |
the store password (required) |
ANDROID_KEY_PASSWORD |
the key password (optional; defaults to store password) |
ANDROID_KEY_ALIAS |
the alias (optional; defaults to upload) |
Produce the base64 (PowerShell):
[Convert]::ToBase64String([IO.File]::ReadAllBytes("$env:USERPROFILE\jsonprism-upload-keystore.jks")) | Set-Clipboard
CI decodes it to a temp path, writes keystore.properties, builds with
tauri android build --apk, and uploads the universal APK to the same draft
release as the desktop bundles. If ANDROID_KEYSTORE_BASE64 is unset the job
fails fast rather than shipping an unsigned APK.
Output
src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk
Offline fonts
Fonts (Geist / Instrument Serif / JetBrains Mono) are self-hosted via
@fontsource (imported in src/main.tsx), not loaded from Google Fonts, so the
app renders correctly offline. The CSP in tauri.conf.json no longer allows the
Google Fonts hosts — keep it that way unless fonts move back to a CDN.
WebView version requirement (important)
The Android app renders inside the device's Android System WebView, which is
Chromium. Tailwind v4 (our CSS) requires Chromium ≥ 111 (@layer, oklch(),
@property). On an older WebView the layout breaks badly (giant icons, unhidden
elements, no responsive layout) even though the app installs and runs.
- Real Android 12+ devices keep WebView updated via Play Store → modern Chromium → renders correctly. This is the normal case.
- The bundled WebView in the API 31 emulator system image is Chromium 91 and
shows the broken layout. Use a newer emulator image (e.g.
android-34+, which ships Chromium ≥ 120) or update the emulator's WebView via Play to test rendering. Theandroid-31install/minSdkgate can still be tested on the stock API 31 image.
This is inherent to the Tailwind v4 stack (the web app has the same requirement); it is not Android-specific code. No action needed unless you must support devices with a very outdated WebView.
Native file I/O on Android
plugin-dialog open() returns a percent-encoded content:// URI on Android
(not a filesystem path). plugin-fs readTextFile() reads it fine — validated on
an emulator for both URI flavours. fileFromNativePath() (src/lib/tauri.ts)
runs the URI through basenameFromPath() to recover a filename for the editor,
the extension filter, and toasts. stat() on a content URI is unreliable, so
lastModified falls back to a deterministic path hash — dedup still works.
Two URI flavours show up:
raw:URIs (most local/Downloads files) embed the real path →basenameFromPath()recoversdata.json.msf:URIs (MediaStore-indexed files) are opaque document ids with no filename → they collapse to a numeric id (e.g.18) and carry no extension. The native open path therefore filters leniently (filterByExtension(..., true)/ theextOf(name) && !allowedguard inInputPanel) so a file the user explicitly picked is never wrongly rejected. The real display name would need a content-resolverDISPLAY_NAMEquery via a custom Rust command — not worth it; the file content loads correctly either way.