Native Development Roku

Use the Roku-shaped browser runtime for fast shared UI work, then validate on physical Roku hardware. The browser renderer cannot reproduce SceneGraph execution, device networking, memory pressure, packaging, or firmware behavior.

Prerequisites

• Enable developer mode by following Roku’s developer setup guide.
• Install project dependencies and the compiler configured in hosanna.json.
• Put the installer password in ROKU_DEVPASSWORD or a secure local/CI secret store. Do not commit it or place it directly in a reusable command.
• Define the device in the project or user HST configuration, or select it from discovery.

Check the resolved targets before the first deployment:

npx hst target:list roku
npx hst run roku dev device \
  --device "Living Room Roku" \
  --dry-run \
  --explain

Browser-to-Device Workflow

Run the Roku-shaped browser profile for fast layout, state, focus, and API work:

npx hst run roku dev browser

Build without deploying when you want to inspect compiler output:

npx hst build roku dev device \
  --hsc-project platforms/hsconfig-roku.dev.json

Build, deploy, launch, and stream logs from a device:

npx hst run roku dev device \
  --device "Living Room Roku" \
  --hsc-project platforms/hsconfig-roku.dev.json \
  --source-root platforms/roku/src

When generated output is already current, --no-build skips compilation and redeploys that output:

npx hst run roku dev device \
  --device "Living Room Roku" \
  --source-root platforms/roku/src \
  --no-build

Do not use --no-build after changing TypeScript, build config, compiler settings, generated views, or static assets.

Roku Compiler Project

Hosanna projects normally keep environment-specific compiler projects such as:

platforms/hsconfig-roku.dev.json
platforms/hsconfig-roku.debug.json
platforms/hsconfig-roku.prod.json

Select one with --hsc-project or put it in .hosanna-tools/run.json. Keep environment differences deliberate: the sample repository enables useful debug output in development and disables console output and debug-only flags in production.

The main sections are:

Setting	Purpose
files	TypeScript, generated source, BrightScript, XML, and JSON inputs
staticFiles	Files copied into the Roku package, plus negative globs for exclusions
excludedFiles	Source trees the compiler must not process
outDir	Generated component output
tsConfig	Roku TypeScript configuration
transpileOptions	Compiler output, logging, and optimization choices
sourceGenerationOptions	Roku bundle paths, limits, filenames, and XML script injection
buildFlags	Compile-time __FLAG__ values
diagnosticFilters	Intentionally suppressed compiler diagnostics

Use hosanna-ui-samples-public/platforms/hsconfig-roku.dev.json and .prod.json as current working references. Do not copy their asset exclusions or diagnostic filters blindly; each entry should have an app-specific reason.

Static Assets

staticFiles copies non-TypeScript inputs to the package. Object entries specify a source and destination; negative glob strings exclude matches:

{
  "staticFiles": [
    {
      "src": ["assets/**"],
      "dest": "../assets"
    },
    "!assets/**/.DS_Store",
    "!assets/meta/mock-data/**"
  ]
}

Positive string entries preserve their source path under the output package:

{
  "staticFiles": [
    "manifest",
    "assets/images/splash-screen-fhd.jpg"
  ]
}

Inspect the packaged tree before release. An exclusion can remove a required asset just as easily as it can reduce package size.

Main Loop Mode

The host source/main.brs should remain a small trampoline into the generated Hosanna main loop:

sub Main(launchArgs as object)
    hs_run_main_loop(launchArgs)
end sub

buildFlags.ROKU_RENDER_LOOP_EVENT selects the timer-driven or event-driven generated loop at compile time. If the same TypeScript also runs in Vite, define the matching __ROKU_RENDER_LOOP_EVENT__ value there so browser and Roku builds do not compile different assumptions accidentally.

Logs and Source Maps

hst run ... device streams the Roku log and resolves generated locations where source maps are available. For a copied crash or compile trace, map it explicitly:

pbpaste | npx hst roku:map-stack \
  --source-map-root platforms/roku/src

You can also pass --file crash.txt or --text "pkg:/components/source_0.brs(7475)".

Use Hosanna DevTools when you need structured view, focus, state, screenshot, or CollectionView inspection. Use the raw Roku console or a BrighterScript debugger when the fault is below the Hosanna runtime.

Native Roku Code and Libraries

Roku-only .brs and .xml dependencies stay in the Roku project and are copied through the compiler project. Describe external nodes and classes with narrow TypeScript interfaces, then instantiate them through the SceneGraph bridge. Provide a browser fake when shared screens must run without the native library.

For distributable libraries, see Roku Component Libraries.

Release Boundary

Before producing a release candidate:

1. Resolve production build config without developer or test secrets.
2. Compile with the production Roku compiler project.
3. Package the generated manifest, source, components, and required assets using the project’s release script.
4. Inspect the package contents and verify current Roku manifest, signing, package-size, and certification requirements.
5. Install the exact candidate on representative low- and high-capability devices.
6. Test cold launch, deep links, playback, authentication, network recovery, focus, memory pressure, and sustained navigation.

Roku’s platform limits and certification rules can change. Treat the current Roku documentation and release checklist as the authority rather than copying a fixed limit into application docs.