Skip to main content

Building For Android

Use the Android target when the shared Hosanna app needs to run on Android phones or tablets. The app can reuse shared screens, state, AppConfig, fragments, networking, and business logic while Android handles native packaging, lifecycle, and device integration.

Prerequisites​

  • Android Studio with the Android SDK installed.
  • Android emulator images or physical Android devices.
  • Access to the licensed Hosanna framework sources and tooling for the project.
  • Android signing credentials for release builds.
  • The project dependencies installed from the lockfile with npm ci.

Build And Run​

Android delivery lane from the Hosanna JavaScript and asset bundle through the app-owned Gradle project, signing, and Play releaseAndroid delivery lane from the Hosanna JavaScript and asset bundle through the app-owned Gradle project, signing, and Play release

Use hst run for current Android emulator and device work:

npx hst native:prepare android
npx hst native:doctor android
npx hst target:list --platform android --target sim
npx hst run android dev sim --device "Pixel_8"
npx hst target:list --platform android --target device
npx hst run android dev device --device "RF8M62694QT" --no-logs

Use --device to select an ADB serial such as emulator-5554, a physical device serial, or a configured emulator name. Commit common defaults in .hosanna-tools/run.json. HS_ANDROID_AVD remains useful inside local wrapper scripts when no device is connected and a specific phone/tablet AVD should be started.

For hot reload on a real Android device, the launcher usually detects the Mac LAN IP. Set HS_DEV_HOST only when auto-detection picks an unreachable host, then run with --hot-reload.

You can still open the Android project in Android Studio for native debugging, profiling, signing, capabilities, and release builds. Do not use Android Studio or VS Code launch targets as the default app launcher when an hst run path exists.

Capacitor Android scripts are legacy/deprecated for current development. Use them only when explicitly maintaining the old WebView shell.

Use --bundled for release-like JavaScript/assets. In HST terminology, sim is the Android Virtual Device; browser/web/emulator select the browser runtime.

Static Assets​

For bundled Android builds, HST stages hsconfig static files into platforms/android/app/src/main/assets before copying the JavaScript or Hermes bundle. Put hsconfig in .hosanna-tools/run.json or pass --hsconfig:

{
  "rootDir": "..",
  "cwd": "..",
  "outDir": "platforms/android/app/src/main/assets",
  "staticFiles": [
    { "src": "assets/meta", "dest": "meta" },
    { "src": "assets/images", "dest": "assets/images" },
    { "src": "assets/fonts", "dest": "assets/fonts" },
    "!assets/images/dev-only/**"
  ]
}

Use negative staticFiles entries for excludes. Do not use env interpolation; select a different hsconfig file for a different asset set.

Debugging​

  • Use Web for fast shared-runtime checks.
  • Use Android Studio Logcat and debugger for native logs, lifecycle, memory, and packaging issues.
  • Validate touch input, text input, orientation, safe areas, networking, app resume, and low-memory behavior.

See Android for platform-specific runtime notes.

Talk to us