Guide · v0.13.8

Android

The same TSX (or Go) app builds into an APK or an App Bundle. The npm package ships the Android runtimes, so tarve build --target android works from Windows or Linux without Rust or the NDK. You develop on the desktop and build for the phone.

Build and install

terminal
bunx tarve build app.tsx --target android                    # dist/App.apk (arm64-v8a + x86_64)
bunx tarve build app.tsx --target android-arm64              # one ABI
bunx tarve build app.tsx --target android --runtime bun      # Bun on the device
bunx tarve build app.tsx --target android --format aab --keystore upload.jks   # Google Play
bunx tarve build go/examples/counter --target android        # a Go main package
adb install dist/App.apk
adb logcat -s tarve                                           # console.log goes to logcat

You need the Android SDK (build-tools and a platform, from ANDROID_HOME) and a JDK; Go apps also need the NDK. APKs are signed with the debug keystore unless --keystore or TARVE_ANDROID_KEYSTORE names one; Google Play rejects the debug key. Without a phone, bun run android:emulator in the repository starts a headless Android 15 emulator in Docker. Signing, App Bundles and the other build options are in Build and package.

What works

AreaOn Android
Components, layout, text, styles, motionSame as on the desktop: the same native runtime lays out and paints them.
InputTouch is the pointer (tap clicks, hold and drag, swipe scrolls, onLongPress, onPinch); the soft keyboard follows input focus and reopens on a tap into the focused field; Back sends onCloseRequest (the router goes back).
Audio and video<audio> on the app's own decoder, <video> on MediaPlayer (hardware decoders); playback continues in the background with a media notification, lock-screen and headset controls. See Audio and video.
Device APIsPermissions, location, biometrics, share, notifications (also at a time or a place with the app closed), speech recognition, deep links and file associations, webSignIn. Several of these exist only on Android; see Platform APIs.
Filesnode:fs works in the app's private storage (os.homedir(), os.tmpdir()); the file dialogs open the system document picker and copy the chosen document into the cache. Folders are not supported.
Not availableTray (a no-op that reports supported: false), desktop widgets, native menus, several windows, window position and size.

Permissions and network

Every APK declares INTERNET, the media playback foreground service, POST_NOTIFICATIONS and WAKE_LOCK. Add your own in package.json (a name without a dot is an android.permission. one) or with --permission. Android blocks plain http://, media included; cleartextTraffic allows it (a media server on the LAN).

package.json
{
  "tarve": {
    "android": {
      "permissions": ["CAMERA", "RECORD_AUDIO", "ACCESS_FINE_LOCATION"],
      "cleartextTraffic": true
    }
  }
}

Dangerous permissions also need consent at run time. On Windows and Linux both calls answer "granted", so the same code runs everywhere.

app.tsx
const states = await app.requestPermissions(["CAMERA", "RECORD_AUDIO"]); // { CAMERA: "granted", RECORD_AUDIO: "denied" }
const now = await app.checkPermissions(["CAMERA"]);                     // no prompt: "granted" | "prompt" | "denied"

Differences from the desktop

TopicDetails
Where you developOn Windows or Linux with tarve dev, or on the device: tarve dev app.tsx --target android installs a dev APK once, then on every save rebundles only the JS, pushes it with adb and restarts the app (about 0.7 s on an emulator, no reinstall). The app's console and crashes print in the terminal; a bundling error leaves the last good app running. --device <serial> or ANDROID_SERIAL picks the device.
JavaScript engineQuickJS-ng inside the runtime (a few MB): timers, fetch, TextEncoder, URL, crypto, Intl, Buffer, node:fs/path/os/crypto, no child processes or sockets. --runtime bun ships Bun instead (its full API, about 45 MB more per ABI). Node.js has no Android build.
Pluginstarve build packs each plugin's android-arm64 / android-x64 library from tarve.native into the APK (named lib<name>.so), and ctx.loadLibrary opens it through the runtime's FFI: up to 8 integer/pointer and 8 floating-point arguments, no variadic functions, tagged pointers as BigInt. See Plugins.
RendererVello on the GPU (wgpu), with the CPU renderer as fallback; D3D11 is Windows only.
Target SDKAPI 35, edge-to-edge: the window background paints behind the status and navigation bars, and the UI is laid out inside them, the display cutout and the keyboard. Check Google Play's current requirement before uploading.
How it is testedEvery change to the runtime runs an APK on an Android 14 emulator in CI (scripts/smoke-android-ci.tsx): rendering, layout, a click and a long press, timers and storage, <video> (metadata, playback, seek) and <audio> from files bundled in the APK, the Back key reaching onCloseRequest, and the device APIs that answer without a person (checkPermissions, notify posting to the shade, recognizeSpeech answering). The release workflow builds and ships both ABIs. Pinch, the share sheet, location, biometrics, real dictation and playback on hardware decoders are still checked by hand on a phone (Galaxy S23, Android 15).