Skip to main content

Setup

Installation​

Hosanna application lifecycle from locked dependency installation through target builds and platform-owned packagingHosanna application lifecycle from locked dependency installation through target builds and platform-owned packaging

Install Dependencies​

Install the exact dependency graph from the app lockfile:

npm ci

Use Hosanna Tools From The Project​

Hosanna Tools is normally installed as a project dependency and run through npx hst. Do not rely on a machine-wide hst for app builds, because the repo lockfile is the source of truth for the tool version.

npx hst --help
npx hst env check

The current sample app uses Hosanna Tools ^3.10.2 and Node.js 24.17.0. Another app may pin different compatible versions; its lockfile, .nvmrc, package.json, and hosanna.json are authoritative.

Install Hosanna Compiler (HSC)​

Restore the configured SDK and compiler through Hosanna Tools:

npx hst sdk:install
npx hst compiler:install
npx hst compiler:status

These commands require the active Hosanna license. The compiler is installed as ./bin/hsc; the framework source is installed into the app-local hosanna-ui/ root.

Development Workflow​

Editing Code​

Use any TypeScript-capable editor. The Hosanna UI and BrightScript editor extensions can help with navigation and optional breakpoint sessions, but the primary app workflow is terminal-first through npx hst.

Developer Process​

Before committing changes, follow these steps:

  1. Run the linter:

    npm run lint

  2. Run tests:

    npm test

  3. Commit changes: Use meaningful commit messages.

Web Development​

Browser Runtime​

Use the browser target for faster debugging across shared UI, focus, input, AppConfig, and fragment behavior:

npx hst run web dev browser

This resolves Web runtime build config, starts or reuses Vite and Hosanna Tools services, and opens the browser. For a platform-shaped browser preview, use another platform with the browser target, such as npx hst run roku dev browser or npx hst run ios dev browser --device iphone-15.

Platform Targets​

Use hst run and hst build when validating a release:

  • Roku: npx hst build roku dev device and npx hst run roku dev device --device "<roku name or ip>".
  • Apple TV and iOS: npx hst run apple-tv dev sim and npx hst run ios dev sim; use device for hardware.
  • Android TV and Android: npx hst run android-tv dev sim and npx hst run android dev sim; use device for hardware.
  • Samsung TV: Samsung TV package built from the web target.
  • Web: npx hst run web dev browser and the app's npm run build.

Run npx hst target:list --form-factor tv --json or npx hst target:list --platform ios --target sim --json when you need to choose a target explicitly.

Documentation​

Explore the docs folder for detailed information:

  • Platforms: release-target setup and validation notes.
  • UI and Interaction: views, focus, input, styles, fragments, and controls.
  • Tools: Hosanna Tools, compiler, DevTools, MCP debugger, and diagnostics.
  • Deployment: packaging, versioning, and CI.
Talk to us