Skip to main content

Roku Apps

Prerequisite: Enable Developer Mode​

Before you can run or debug Roku apps, your Roku device must be in developer mode. See Roku Developer Mode Setup.

Running and Debugging Roku Apps​

Use the command-line workflow:

npx hst target:list --platform roku
npx hst build roku dev device
npx hst run roku dev device --device "Living Room Roku" --replace

hst run compiles when needed, deploys to the selected Roku, and streams logs. Use --no-build --source-root platforms/roku/src when you have already built and only need to redeploy generated output.

Breakpoints and BrighterScript tooling remain available for targeted sessions, but do not make VS Code launch targets the default way to run a Roku app. Prefer hst run, Hosanna DevTools, MCP debugger tools, source maps, and terminal logs for daily debugging.

Logging​

  • Use the supported console methods such as log, debug, info, warn, and error.
  • hst run streams device logs in the terminal and applies source-map path resolution where available.
  • For production builds, set logLevel to off in hsconfig-roku.json to strip logs (they remain as comments for readability).

Mapping Crash and Compiler Output​

Use npx hst roku:map-stack to map generated BrightScript locations from Roku crash reports, telnet stack traces, or compiler output back to TypeScript source lines:

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

It supports Roku file/line: pkg:/...brs(123) frames, at ... (pkg:/...brs:123) stack traces, compile errors, and bare generated references such as source_10.brs:8211. See Roku Stack Source Maps.

Tips​

  • Use npx hst run roku dev device --no-build --source-root platforms/roku/src for faster redeploys after a successful build.
  • Network requests print curl statements for easy manual testing.
  • Use hs_native_roku(\print foo | stop`)` to inject ad hoc BrightScript code.
  • You can debug via telnet or sideload manually by zipping the src folder.
  • Inspect the final channel archive and apply the application's current package policy before release. The sample package task rejects source maps and other forbidden development output.
  • The manifest contains required channel metadata; release automation should stamp it deterministically rather than relying on ad hoc edits.

Breakpoint Debugging​

  • Optional breakpoint sessions can still use VS Code and BrighterScript against generated BrightScript and source maps.
  • For routine issues, start with terminal logs, roku:map-stack, Hosanna DevTools, and the MCP debugger.
  • See Native Development Roku for more details.

Chrome DevTools Extension​

Editor Extension​

  • Install the Hosanna UI editor extension when you want source navigation, templates, and optional source-map conveniences. It is not required for hst run.

Special Launch Query Strings​

  • Use query parameters for deeplinking and commands:
    • ?mediaType=movie&contentId=12345 for deeplinking.
    • ?textToSpeech=true to enable text-to-speech.
    • ?mediaType=hosannaCommand&contentId=clearRegistry to clear the registry.

For more details, see:

Talk to us