Native Development Roku

Prerequisite: Enable Developer Mode on Your Roku

Before deploying and debugging apps on a Roku device, you must enable Developer Mode. Follow Roku's official instructions here: Roku Developer Mode Setup

Once Developer Mode is enabled, you can sideload and debug your Hosanna app directly from VSCode.

Hosanna UI enables a fast and productive workflow for Roku development by allowing most development and integration testing to be done in the browser emulator. Once your features are stable, you can easily test and debug on a real Roku device.

Workflow Overview

1. Develop in the Browser Emulator: Use the browser-based emulator for rapid development, UI iteration, and integration testing. This provides fast feedback and avoids the need to deploy to device for every change.

2. Test on Device: When ready, run your app on a Roku device for final integration and native testing. This ensures your app works as expected in the real environment.

Running on Device

• Use the [ROKU] launch target in VSCode. This target:

  • Runs the transpile task to convert TypeScript to BrightScript.
  • Uses the BrighterScript plugin to bundle and deploy your app to the Roku device.
  • Supports breakpoints and debugging in both .brs and .ts files, thanks to Hosanna's source map generation.
  • Stops at crashes and exceptions at the correct source line.

• Tip: Enable the Hosanna extension's source sync feature for seamless code updates and debugging when running on device.

Prerequisites

• BrighterScript: Ensure BrighterScript is installed. It provides bundling, deployment, and breakpoint support for Roku development.

• Preconfigured Launch Targets: Hosanna projects come with preconfigured launch targets for Roku. All Roku-specific files are located in the Roku project directory.

hsconfig-roku.json: Configuration

The hsconfig-roku.json file controls how your Roku code is transpiled and bundled. Key options include:

• isVirtualBuild: Enables virtual builds (no file output).
• isWritingFiles: Controls whether transpiled files are written to disk.
• generateReflectionData: Generates reflection metadata for components.
• logLevel: Sets the logging level (info, debug, etc.).
• outDir: Output directory for transpiled Roku components.
• files: Glob patterns for source files to include.
• staticFiles: List of static resources to copy (with src and dest).
• tsConfig: Path to the TypeScript config for Roku builds.
• excludedFiles: Patterns for files and directories to exclude from the build.
• transpileOptions:
  • indent: Indent output code.
  • generateIndividualSourceWhenBundling: Generate individual source files when bundling.
  • includeComments: Include comments in output.
  • logLevel: Transpiler logging level.
  • emitConsoleFilePathPrintStatements: Print file paths in console output.
• sourceGenerationOptions:
  • platform: Target platform (e.g., roku).
  • sourceMode: Bundling mode.
  • maxLines, maxKb: Bundle size limits.
  • bundlePath, bundleFileTemplate: Bundle output settings.
  • xmlScriptTemplates: XML templates for script imports.
• diagnosticFilters: List of diagnostic codes to filter out.

Example hsconfig-roku.json:

{
  "isVirtualBuild": false,
  "isWritingFiles": true,
  "generateReflectionData": true,
  "logLevel": "info",
  "outDir": "./platforms/roku/src/components",
  "files": [
    "src/**/*.ts",
    "src/**/*.brs",
    "src/**/*.xml",
    "src/**/*.json"
  ],
  "staticFiles": [
    { "src": "./platforms/roku/DebugTools", "dest": "./debugTools" },
    { "src": "assets", "dest": "../assets" }
  ],
  "tsConfig": "./tsconfig.roku.json",
  "excludedFiles": [
    "**/node_modules",
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/web/*",
    "**/common-native/*",
    "**/apple/*",
    "**/play/*"
  ],
  "transpileOptions": {
    "indent": true,
    "generateIndividualSourceWhenBundling": true,
    "includeComments": false,
    "logLevel": "info",
    "emitConsoleFilePathPrintStatements": true
  },
  "sourceGenerationOptions": {
    "platform": "roku",
    "sourceMode": "bundle",
    "maxLines": 20000,
    "maxKb": 400,
    "bundlePath": "",
    "bundleFileTemplate": "source_${index}.brs",
    "xmlScriptTemplates": [
      {
        "path": "hosanna-ui/app-roku/HosannaApp.xml",
        "scriptPlaceholder": "<!-- HOSANNA_SCRIPT_IMPORTS -->",
        "scope": ["all"]
      }
    ]
  },
  "diagnosticFilters": ["HS-1038", "HS-1058"]
}

Adjust these settings as needed for your project to control build output, logging, static resources, and more.

Breakpoint Debugging

Hosanna UI supports full breakpoint debugging on Roku devices, thanks to integrated source maps and BrighterScript tooling.

• You can set breakpoints in both .ts (TypeScript) and .brs (BrightScript) files directly from VSCode.
• When you run the [ROKU] launch target, the transpiler generates source maps that map your TypeScript code to the transpiled BrightScript.
• The BrighterScript plugin will pause execution at your breakpoints, allowing you to inspect variables, call stacks, and step through code.
• If your app crashes or throws an exception, the debugger will stop at the exact line in your source code.

Tips for effective debugging:

• Make sure you have the BrighterScript VSCode extension installed.
• Use the Hosanna extension's source sync feature for live updates.
• You can inspect and modify state, step through code, and use all standard VSCode debugging features.

Breakpoint debugging works seamlessly for both integration and native device testing, making it easy to diagnose issues and verify app behavior.

Logging

Hosanna UI supports logging at various levels: info, debug, error, and verbose. You can include log statements in your code, and when running on device, these logs will appear in the console and are clickable in the IDE, allowing you to jump directly to the source line.

Example:

console.log('This is an info log');
console.debug('Debug details here');
console.error('Something went wrong');
console.verbose('Verbose output for tracing');

Best Practices:

• Use appropriate log levels for different types of output.
• For production builds, set the log level to off in your configuration. This strips out all console log statements from the transpiled code.
• When logs are stripped, the statements remain as comments in the output code for readability and traceability.

Configure log level in hsconfig-roku.json:

{
  "logLevel": "off"
}

This ensures clean production builds without unnecessary logging, while keeping your code easy to audit and debug during development.

Tips & Best Practices

• VSCode Debugging: Use the BrighterScript extension for console output, filtering, and searching logs directly in VSCode.

• Network Requests: All network requests print equivalent curl statements to the console. You can copy and paste these into your terminal for manual testing.

• Ad Hoc Roku Code: Use hs_native_roku(\print foo | stop`)` to inject ad hoc BrightScript code for quick debugging or inspection.

• Skip Transpiling for Faster Debug: You can run the [ROKU] launch target without transpiling to speed up the debug cycle if your code hasn't changed.

• Telnet Debugging: You can connect to your Roku device via telnet for low-level debugging if needed.

• Manual Sideload: You can sideload your app without the extension by zipping up the src folder and uploading it via the Roku Developer web interface.

• Roku Zip Size Limit: Roku channel zip files must be less than 4MB to be accepted by the Roku store and to launch correctly.

• Manifest File: The manifest file in your Roku project contains required metadata for Roku releases. You can edit this file to update version, title, and other release info.

Summary

• Develop primarily in the browser emulator for speed.
• Use the [ROKU] launch target for device testing and debugging.
• Ensure BrighterScript is installed for bundling and breakpoints.
• Configure your build with hsconfig-roku.json for full control over the Roku transpilation process.

For more details, see the guides on launch targets and configuration.