Skip to main content

Javascript Runtime Implementation

Roku devices do not natively support JavaScript; instead, they use BrightScript as their primary language. Hosanna is unique in that it provides a JavaScript transpiler that polyfills essential JavaScript features, enabling developers to write code in TypeScript and run it on Roku devices.

The Hosanna transpiler is optimized specifically for BrightScript and structures the generated code in the most efficient way possible for Roku hardware. While many JavaScript features are supported, not everything can be implemented or is advisable for performance reasons. Hosanna includes diagnostics to alert you when you use unsupported features or code patterns that may perform poorly. In most cases, it will also suggest suitable workarounds to help you adapt your code for the Roku environment.

Transpiler Diagnostics​

The Hosanna compiler (hsc) outputs diagnostics to the terminal during the build process. These diagnostics help identify unsupported features, potential performance issues, or code that may not behave as expected on Roku devices. When using VSCode, the provided tasks and launch commands are configured to inject these diagnostics and display them directly in the IDE for a streamlined development experience.

Filtering Diagnostics​

You can filter out specific diagnostics in your hsconfig.json file using their diagnostic codes. For example:

"diagnosticFilters": [
  "HS-1038",
  "HS-1058"
]

Additionally, you can suppress diagnostics for a specific line in your code using a comment, similar to TypeScript:

//hs: disable-next-line
someUnsupportedOperation();

//hs: disable-next-line HS-1038 HS-1058
anotherOperation();

This allows you to either disable all diagnostics for the next line or target specific diagnostic codes.

Advice on Diagnostics​

We strongly recommend reviewing all warning diagnostics. The best way to do this is to use the source map feature to view the generated BrightScript (.brs) code side by side with your original code. This helps you determine if a diagnostic can be safely ignored or if your code has been rewritten for better performance or accuracy. Note that some diagnostics may be silent, and some code may be automatically transformed to improve compatibility or efficiency.

Interop and tasks​

Hosanna's JS runtime interoperates with Roku SceneGraph tasks and nodes. When passing data or behavior across boundaries, avoid capturing closures or complex references that cannot be serialized.

Passing function references across node/task boundaries​

Use an AsyncFunctionPointer to reference a function by module and export name. This allows the runtime to resolve the function in the receiving context and execute it safely.

// hosanna-api
export type AsyncFunctionPointer = { module: string; exportName: string };

// usage when dispatching work
this.dispatch(Http.Get, {
  url: 'https://api.example.com/data',
  transformFunction: { module: './transformFunctions', exportName: 'processRows' }
});

// In the background context, resolve and invoke via a helper (e.g., getAsyncFunctionFromPointer)

This is especially useful when you need to process results in a background task without blocking the main thread.