Running On Device

Use Hosanna Tools from the terminal for browser, simulator, and physical-device runs. VS Code launch targets may exist in older projects as compatibility fallbacks, but the primary workflow is npx hst run plus npx hst target:list.

General Flow

1. Develop shared UI, state, AppConfig, fragments, and input behavior in Web.
2. List available targets with npx hst target:list.
3. Run the platform target with npx hst run.
4. Validate startup, focus or touch input, navigation, networking, media playback, lifecycle resume, logging, and performance.

npx hst target:list --form-factor tv --json
npx hst target:list --platform ios --target browser --json
npx hst target:list --platform ios --target sim --json
npx hst target:list --platform android --target sim --json

Use --dry-run --explain when you need to audit how HST resolved a launch:

npx hst run ios dev browser --device iphone-15 --dry-run --explain
npx hst run android dev sim --device Pixel_8 --dry-run --explain

Platform Paths

• Roku: use npx hst run roku dev device --device "<roku name or ip>"; add --replace when replacing an existing recorded session.
• Apple TV and iOS: use npx hst run apple-tv dev sim, npx hst run apple-tv dev device, npx hst run ios dev sim, or npx hst run ios dev device. Use Xcode for signing, profiling, and release tooling.
• Android TV and Android: use npx hst run android-tv dev sim, npx hst run android-tv dev device, npx hst run android dev sim, or npx hst run android dev device. Use Android Studio for signing, profiling, and Play Store release tooling.
• Samsung TV: build the Samsung TV package from the web target, then validate on Samsung TV hardware.
• Browser previews: use npx hst run web dev browser, npx hst run roku dev browser, or another platform browser target with Vite, browser DevTools, Hosanna DevTools, and the MCP debugger.

Device selection should be explicit for repeatable runs:

npx hst run web dev browser
npx hst run roku dev browser
npx hst run ios dev browser --device iphone-15
npx hst run roku dev device --device "Living Room Roku" --replace
npx hst run ios dev sim --device "iPhone 17 Pro"
npx hst run ios dev device --device "My iPhone" --no-logs
npx hst run apple-tv dev sim --device "Apple TV 4K"
npx hst run android dev sim --device "Pixel_8"
npx hst run android-tv dev sim --device "Television_1080p"

Target Types

browser starts the platform-shaped Web runtime. It is the fastest development loop and can apply presets such as iphone-15, pixel-8, apple-tv-4k, android-tv-1080p, and rokufhd.

sim is for the vendor virtual device: Apple Simulator on iOS and Apple TV, Android Emulator on Android and Android TV. device is for physical hardware. Roku supports the browser runtime and physical device runs; HST does not have a Roku sim target.

The DevTools device simulator is different from all of these: it is an inspection panel that sends design-coordinate hover/click/key events to a running web or device app.

web, browser, emulator, and emulated all select the browser runtime. simulator and simulated select sim. These docs use browser, sim, and device to keep an Android Emulator distinct from a browser emulation preset.

Run Defaults

Commit shared launch defaults in .hosanna-tools/run.json so humans and agents do not have to remember ports, default target kinds, or common sim names:

{
  "schemaVersion": 1,
  "defaults": {
    "appName": "my-hosanna-app",
    "vitePort": 5175,
    "platforms": {
      "web": { "target": "browser", "vitePort": 5175 },
      "roku": { "target": "device" },
      "ios": { "target": "sim" },
      "apple-tv": { "target": "sim" },
      "android": { "target": "sim", "device": "Pixel_8" },
      "android-tv": { "target": "sim", "device": "Television_1080p" }
    }
  }
}

For repos with multiple apps or flavors, add apps entries and select one with --app:

{
  "schemaVersion": 1,
  "defaults": {
    "appName": "hope-stream-hosanna",
    "platforms": {
      "ios": { "target": "sim" },
      "android": { "target": "sim" }
    }
  },
  "apps": {
    "hope-stream": {
      "appName": "hope-stream-hosanna",
      "platforms": {
        "ios": {
          "profile": "native-device",
          "passthroughArgs": ["--app", "hope-stream"]
        }
      }
    },
    "adventist-plus": {
      "appName": "adventist-plus-hosanna",
      "platforms": {
        "ios": {
          "profile": "adventist-plus-native-device",
          "appConfig": "adventist-plus.phone",
          "passthroughArgs": ["--app", "adventist-plus"]
        }
      }
    }
  }
}

npx hst run ios dev device --app hope-stream --device "My iPhone"
npx hst run ios dev device --app adventist-plus --device "My iPhone"

Run config is layered from home defaults, project defaults, selected app/flavor, platform defaults, environment variables, and CLI flags. Use --app or HOSANNA_RUN_APP to select an entry from apps; use --profile for build-config overlays; use --app-config for runtime AppConfig selection. See White-Label Apps for app/flavor examples.

--device is preferred for one-off runs. HS_TARGET and platform-specific variables such as HS_ANDROID_AVD remain useful for local shell scripts, but committed docs should prefer explicit CLI flags or .hosanna-tools/run.json.

Use Capacitor launch scripts only for explicit maintenance of the legacy WebView shell.

For target-specific details, see Platform Support and the platform page for your release target.