A production-ready starter kit for building modern Roku apps using BrighterScript, NodeJS tooling, and a modular, scalable architecture.

🚀 Build Roku apps the modern way - with TypeScript-like BrighterScript, navigation state, debugging tools, and an opinionated project structure that’s ready for production from day one.

📸 Screenshots

Home Screen	Details Screen
Playback Screen	Error Screen
Exit Confirmation Modal

✨ Features

Feature	Description
⚡ BrighterScript Support	Modern TypeScript-like language for Roku (classes, interfaces, constants, enums, namespaces, null-Coalescing Operator, transpiled to BrightScript)
🛠 Node Build Pipeline	Transpilation, validation, packaging, and deployment directly to a Roku device
🧭 Stack-Based Router	Navigate between screens with full state and history management
📣 Global Event Bus	Lightweight publish/subscribe for app-wide events without tight coupling
🚪 Exit Confirmation Modal	Back‑key exit confirmation when there is no navigation history
🌐 HTTP Helper	Built-in class for clean, reusable API calls
🧩 Modular Project Structure	Screens and components separated for maintainability and scale
🧪 RALE Debug Integration	Automatically bundles Roku’s debug extension for advanced inspection
✅ Production Ready	Designed to be extended, white-labeled, or used as a foundation for commercial apps

🚀 Quickstart

# 1. Clone this repo (Or click the 'Use this template' button)
git clone git@github.com:twig2let/roku-brighterscript-starter.git
cd roku-brighterscript-starter

# 2. Install dependencies
npm install

# 3. Create a `.env` in the root of the project.
ROKU_IP=YOUR-ROKU-DEVICE-IP-ADDRESS
ROKU_DEV_USER=rokudev
ROKU_DEV_PASSWORD=rokudev

# 4. (Optional) Build & deploy to your Roku device…
npm run roku-deploy

👉 See the VSCode Brightscript Extension section for a (better) alternative deployment method

🧰 Build & Release

Builds are driven by ENV:

# Development build (source maps on, TrackerTask included)
ENV=dev npm run build

# Production build (source maps off, minified, no TrackerTask)
ENV=prod npm run build

# Shortcut for prod builds
npm run build:prod

Release assets are created from out/transpiled:

npm run release

Release workflow notes:

• The GitHub Release workflow runs on published releases.
• The release tag must match package.json version (e.g. 1.2.3 or v1.2.3).
• The app manifest version (major_version.minor_version.build_version) must match package.json.

📝 VSCode Brightscript Extension

Supported out-of-the-box! This Roku community extension is jam-packed with features, including:

• Full debugger support including breakpoints, variable inspection, and more
• Integrated telnet logs and interactive console
• Client-side syntax checking powered by the BrighterScript language server
• Syntax highlighting, code formatting, symbol navigation, and much more

Just run the Debug launch task in the VSCode IDE.

📁 Project Structure

├─ .vscode/ #
├─ app/
│ ├─ components/ # UI fragments: common widgets, screen presenters, SDK-specific pieces
│ │ ├─ common/ # Shared components reused across screens
│ │ ├─ itemComponents/ # UI bits for item tiles, rows, etc.
│ │ ├─ screens/ # Screen-level component implementations
│ │ └─ sdk/ # Framework-grade UI/tasks (buttons, router, HTTP task) reusable across apps
│ ├─ fonts/ # Typefaces bundled with the channel
│ ├─ images/ # Channel art (icons, splash, dimmers, view assets)
│ └─ source/ # BrighterScript source code (For code without an associated XML file)
│   ├─ facades/ # Facade classes abstracting framework APIs
│   ├─ libs/ # Shared libraries/helpers
│   ├─ parsers/ # Data parsing/normalisation logic
│   └─ sdk/ # Framework-grade non UI related code (EventBus, utilities, etc.)
├─ pipeline/ # Build/deployment pipeline scripts
└- bsconfig.json # BrighterScript config

✅ Opinionated structure for clarity

✅ Designed for commercial-scale apps

✅ Easy to extend with additional modules

🧭 Routing & Navigation

This starter includes a stack-based router, enabling:

• Push/pop navigation
• Screen parameters
• Back navigation history
• State persistence

Example usage:

SDK.Navigation.Router.NavigateTo(App.Constants.RouteDefintions.HOME, { data: viewData })

📣 Event Bus

The app includes a global EventBus for decoupled, app‑wide events:

SDK.EventBus.on("player:time", sub(payload)
    ?`time in ms: ${payload.ms}`
end sub)

SDK.EventBus.emit("player:time", { ms: 12345 })

🚪 Exit Confirmation Modal

When the user presses Back and there is no navigation history, the app shows an exit confirmation modal. The modal emits events via the EventBus:

SDK.EventBus.emit(App.Constants.Events.EXIT_APP)
SDK.EventBus.emit(App.Constants.Events.CLOSE_EXIT_CONFIRMATION)

🌐 HTTP Helper Example

App.Helpers.HTTP.makeRequest("GET", "https://api.tvmaze.com/shows", invalid, sub(response as Object)
    if NOT response.ok
        SDK.Navigation.Router.NavigateTo(App.Constants.RouteDefintions.ERROR)
        return
    end if

    buildView(response.json)
end sub)

🧠 Why BrighterScript?

BrighterScript is a modern superset of BrightScript that includes:

• Compile-time validation to reduce runtime crashes
• Classes and inheritance
• Namespaces
• Ternary operator
• Null-coalescing operator
• Works with standard BrightScript (.brs) files
• It's actively maintained with a strong community behind it!

🤝 Contributing

Contributions are welcome! Feel free to open issues, submit PRs, or suggest features.

📄 License

MIT License — free to use, extend, and commercialise.

Frequently Asked Questions

Is this starter kit production ready? Yes — it's designed for commercial use, agencies, and Roku channels that need reliability and scalability.

What is the difference between BrightScript and BrighterScript? BrighterScript is a modern superset of BrightScript with TypeScript-like syntax, classes, types, and tooling support.

Can I use this starter to build a Roku channel for my business or client? Absolutely. This repository is intended to be a production foundation for real-world Roku apps.