# Build and package

`tarve build` compiles an app into one executable with the native runtime inside; `tarve package` turns it into installers and archives; `--target android` writes an APK or App Bundle.

## Executables

The npm package carries the Windows x64 and Linux x64 runtimes, so either target builds from either machine without a Rust toolchain. Bun and Node.js builds produce GUI executables named and versioned after the app (`--name`, `--version`).

```sh
bunx tarve build app.tsx --outfile dist/App.exe                      # Bun
npx tarve build app.tsx --outfile dist/App.exe                       # Node.js
bunx tarve build app.tsx --target linux-x64 --outfile dist/App
bunx tarve build app.tsx --runtime txiki --outfile dist/App.exe      # a few MB
bunx tarve build app.tsx --trim --outfile dist/App.exe               # Bun 1.4.4+: leaves unused Bun APIs out
```

`--trim` (`trim: true` in `build()`) uses Bun's `--compile --trim`, which leaves the Bun and Node.js APIs the app never calls out of the executable: `examples/counter` goes from 154.6 to 100.6 MB on Windows. It needs Bun 1.4.4+; an older Bun warns and builds the full runtime, and Node.js and txiki.js builds ignore it. `--aot` (experimental) adds Bun's ahead-of-time compilation; with `--trim` it also drops the JIT (`examples/counter`: 70.1 MB).

## Installers and archives

`tarve package` takes a built executable, or `app.tsx` which it builds first, and writes the packages in pure TypeScript with no external tools. Name, version, icon, description and publisher come from the `tarve` field of `package.json`; flags override them.

```sh
bunx tarve package dist/App --format deb,tar --version 1.2.0 --categories "Utility;Office"
bunx tarve package app.tsx --format zip,msix --version 1.2.0 --publisher "Acme Inc." --out dist/packages
```

| Format | Output |
| --- | --- |
| `deb` | `<app>_<version>_amd64.deb` with `/opt/<app>/<exe>`, a `/usr/bin/<app>` symlink, a `.desktop` entry and a hicolor icon. |
| `tar` | `<app>-<version>-linux-x64.tar.gz` with the executable, `.desktop`, icon and an `install.sh` for a per-user install into `~/.local`. |
| `zip` | `<App>-<version>-windows-x64.zip`, a portable folder. |
| `msix` | An MSIX folder with `AppxManifest.xml` and logos, packed into an unsigned `.msix` when `makeappx` is found (`TARVE_MAKEAPPX`). Sign it with `signtool` using a certificate whose subject is `CN=<publisher>`. |
| `app-zip` | A zipped macOS `.app` bundle (preview, see below). |

Packages declare the app's URL protocols and file types too (`--protocol`, `--file-type ext=Name`, or `tarve.protocols` / `tarve.fileTypes`); see [Platform APIs](https://tarve.dev/docs/platform.md). AppImage is not produced. The API is `packageApp({ executable, format })` from `@tarve/core/package`. For self-updating builds, see [Auto-updates](https://tarve.dev/docs/updates.md).

## Android

`tarve build --target android` writes a signed APK (arm64-v8a and x86_64; `android-arm64` or `android-x64` for one ABI) from Bun or Node.js, for TSX and Go apps. A TSX app runs on QuickJS-ng embedded in the runtime, a few MB; `--runtime bun` ships Bun itself, with its full API, at about 45 MB more per ABI. What works on the device and how it differs from the desktop: [Android](https://tarve.dev/docs/android.md).

```sh
tarve build app.tsx --target android                                   # dist/App.apk
tarve build app.tsx --target android --runtime bun                     # Bun on the device
tarve build app.tsx --target android --format aab --keystore upload.jks # Google Play
tarve build go/examples/counter --target android                       # a Go main package
adb install dist/App.apk
```

| Topic | Details |
| --- | --- |
| Signing | The debug keystore unless `--keystore` or `TARVE_ANDROID_KEYSTORE` (with `TARVE_ANDROID_KEYSTORE_PASSWORD`, `TARVE_ANDROID_KEY_ALIAS`). Google Play rejects bundles signed with the debug key. |
| App Bundles | `--format aab` runs bundletool from `--bundletool`, `TARVE_BUNDLETOOL` or a pinned release downloaded once into the Tarve cache. Tarve targets API 35. |
| Permissions | `INTERNET`, `FOREGROUND_SERVICE`, media playback, `POST_NOTIFICATIONS`, `WAKE_LOCK` and `USE_BIOMETRIC` by default; add more in `tarve.android.permissions` or with `--permission`. Ask at run time with `app.requestPermissions`. |
| Requirements | The Android SDK (build-tools and a platform, from `ANDROID_HOME`) and a JDK; Go apps also need the NDK. `bun run android:emulator` starts a headless emulator in Docker in the repository. |
| Not available | The tray, desktop widgets, native menus and several windows. |

On the device, touch acts as the pointer, the soft keyboard follows input focus, Back requests a close, and `<audio>`/`<video>` keep playing in the background with a media notification and lock-screen controls.

## macOS (preview)

macOS is not a supported target yet. The TypeScript side is in place: `darwin-arm64` and `darwin-x64` targets, `.app` bundles with an `.icns` icon, `tarve package --format app-zip`, and `tarve release` with `--sign "Developer ID Application: …"` and `--notarize`. None of it has been run or signed on a real Mac, and the npm package does not ship a macOS runtime, so building needs `native/darwin-<arch>/libtarve_native.dylib` built on a Mac.

---

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