# 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

```sh
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](https://tarve.dev/docs/shipping.md#android).

## What works

| Area | On Android |
| --- | --- |
| Components, layout, text, styles, motion | Same as on the desktop: the same native runtime lays out and paints them. |
| Input | Touch 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](https://tarve.dev/docs/media.md). |
| Device APIs | Permissions, 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](https://tarve.dev/docs/platform.md). |
| Files | `node: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 available | Tray (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).

```tsx title="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.

```tsx title="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

| Topic | Details |
| --- | --- |
| Where you develop | On 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 engine | QuickJS-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. |
| Plugins | `tarve 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](https://tarve.dev/docs/plugins.md#manifest). |
| Renderer | Vello on the GPU (wgpu), with the CPU renderer as fallback; D3D11 is Windows only. |
| Target SDK | API 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 tested | Every 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). |

---

Tarve v0.13.8 · HTML version: https://tarve.dev/docs/android · Index for agents: https://tarve.dev/llms.txt
