Skip to main content

Platform-Specific Code

Hosanna targets Roku, Apple TV, Android TV, Samsung TV, iOS, Android, and Web. Prefer shared application code first, then isolate platform-specific behavior behind platform initializers, build flags, adapters, or small native interop seams.

Platform Initializers​

Platform-specific bootstrap classes are resolved through @hs-platform aliases. The web target maps these aliases to web implementations; the Roku build maps them to Roku implementations.

{
  "compilerOptions": {
    "paths": {
      "@hs-platform/PlatformAppInitializer": [
        "./src/hosanna-ui/targets/web/app/AppInitializer.web.ts"
      ],
      "@hs-platform/PlatformTaskAppInitializer": [
        "./src/hosanna-ui/targets/web/app/TaskAppInitializer.web.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.

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​