Skip to main content

Platform-Specific Code

Hosanna has first-class Browser, Samsung Tizen, LG webOS, Roku, iOS, Apple TV, Android, Android TV, CarPlay, Android Auto, Apple Watch, and Wear OS launch targets. Prefer shared application code first, then isolate platform-specific behavior behind platform initializers, compile aliases, adapters, or small native interop seams.

Car and watch targets use semantic system-surface entry aliases such as @hs-platform/AppleCarAppEntry, @hs-platform/AndroidAutoAppEntry, @hs-platform/AppleWatchAppEntry, and @hs-platform/WearOsAppEntry. These surfaces reuse domain/state code without pretending an arbitrary phone view tree is portable to a vehicle or watch.

Platform Initializers​

Platform-specific bootstrap classes are resolved through @hs-platform aliases. Browser maps them to shared Web implementations. Tizen and webOS replace only vendor-owned initialization, video, audio guide, device info, lifecycle, and input seams while retaining the Web DOM runtime. Roku maps the same public aliases to Roku implementations.

{
  "compilerOptions": {
    "paths": {
      "@hs-platform/PlatformAppInitializer": [
        "./src/hosanna-ui/targets/tizen/app/AppInitializer.tizen.ts"
      ],
      "@hs-platform/PlatformTaskAppInitializer": [
        "./src/hosanna-ui/targets/web/app/TaskAppInitializer.web.ts"
      ],
      "@hs-platform/PlatformSGVideo": [
        "./src/hosanna-bridge-targets/tizen/sg/TizenSGVideo.ts"
      ]
    }
  }
}
import { PlatformAppInitializer } from '@hs-platform/PlatformAppInitializer';
Do Not Rely on File Names Alone

Extensions such as .roku.ts, .android.ts, or .web.ts are useful conventions, but the alias and build configuration decide which file is used.

Each Web-derived target has its own tsconfig.browser.json, tsconfig.tizen.json, or tsconfig.webos.json. TypeScript replaces nested paths and exclude values rather than merging them, so target configs repeat the complete alias map and exclusions deliberately.

Conditional Compilation Flags​

The Hosanna Compiler supports build-time flags in hsconfig.json:

{
  "buildFlags": {
    "DEV": true,
    "PROD": false,
    "ROKU": true
  }
}

Flags are referenced in TypeScript with double-underscore identifiers:

declare const __DEV__: boolean;
declare const __ROKU__: boolean;
declare const __WEB__: boolean;

if (__DEV__ && __ROKU__) {
  console.info('Roku dev-only code');
}

Supported flag-only expressions include &&, ||, !, and parentheses. The Hosanna Compiler removes unreachable flag-only branches during compilation.

Important constraints:

  • DEV in buildFlags maps to __DEV__; ROKU maps to __ROKU__.
  • __ROKU__ defaults from the target platform when not explicitly set.
  • __PROD__ defaults to the opposite of DEV when DEV is set.
  • Do not mix build flags with runtime values in the same condition.
  • else and elseif are not supported for flag-only conditional compilation.
// Supported
if (__ROKU__ && !__DEV__) {
  enableDeviceOnlyPath();
}

// Not supported: flag mixed with runtime value
if (__ROKU__ && user.isSignedIn) {
  startPlayback();
}

// Not supported: else on a flag-only conditional
if (__WEB__) {
  startWebPath();
} else {
  startDevicePath();
}

Excluding Roku Code​

Use hs:exclude-from-platform roku to exclude a file prefix or a node/line from Roku output.

File-level exclusion must appear in the comment-only prefix before executable code:

// hs:exclude-from-platform roku

export function browserOnlyHelper() {
  return window.location.href;
}

Line or node-level exclusion can be placed directly before the code to skip:

// hs:exclude-from-platform roku
console.info('Web-only debug detail');

Native Roku Code​

Use hs_native_roku sparingly for small BrightScript snippets that cannot be represented in shared TypeScript.

hs_native_roku(`
  print "Hello from Roku"
`);

Keep native snippets small, isolated, and covered by Roku build validation.

Other Hosanna Compiler Directives​

  • // hs:no-module: compile a file as no-module code.
  • // hs:disable-next-line: suppress diagnostics on the next line.
  • // hs:disable-next-line HS-1038 HS-1058: suppress specific diagnostics on the next line.
  • diagnosticFilters in hsconfig.json: suppress diagnostics globally or by source path.

Runtime Detection​

Use runtime platform detection only for small behavioral differences. Prefer build-time separation when a platform imports different APIs or needs code removed from Roku output.

Learn More​

Talk to us