Building from Source

Building from Source

This page takes you from a clean computer to a Moonfin .zip you can sideload onto a Roku. Windows, macOS and Linux all work. You don't need Roku's own tools, only Node.js.

For ready-made packages instead, see Installation and Sideloading.

What you need

Tool	Version	Notes
Node.js	A current LTS release (20 or newer). CI builds on Node 24	Comes with npm
Git	Any recent version	To get the code
A Roku in Developer Mode	Roku OS 9.1 or newer	Only to run your build. Steps under Installation and Sideloading

The compiler (BrighterScript), the linter and the formatter are all installed by npm install. Nothing to install globally.

Step 1: Install Node.js and Git

• Windows: download the LTS installer from nodejs.org and run it with the defaults. Then install Git for Windows. Open a new PowerShell window afterwards.
• macOS: with Homebrew, brew install node git. Or use the installers from the same two sites.
• Linux: your distribution's nodejs, npm and git packages, as long as Node is 20 or newer. nvm or fnm are the easy way to get a current LTS on older distributions.

Check it worked:

node --version
npm --version
git --version

Step 2: Get the code and install

git clone https://github.com/Moonfin-Client/Roku.git
cd Roku
npm ci

npm ci installs exactly the versions in the lock file. npm install works too.

Step 3: Build

npm run build

This clears build/ and out/, compiles the BrighterScript sources and packages the channel according to bsconfig.json. The result is out/Moonfin_Roku_v<version>.zip, where the version comes from package.json. The transpiled BrightScript and the staged channel folder stay under build/staging/ for inspection.

Step 4: Put it on your Roku

With the browser: open http://<the Roku's IP address> on a computer on the same network, sign in as rokudev with your developer password, choose the zip from out/ and click Install. Moonfin starts on the TV. Repeat after every build.

From the terminal: roku-deploy is installed as a dev dependency. It can upload the zip for you once it knows the Roku's address and password:

npx roku-deploy --host 192.168.1.50 --password <your developer password> --rootDir build/staging

See the roku-deploy documentation for the options and for putting those values in a config file instead of the command line.

Checks before a pull request

npm run lint      # compiles with bslint, without packaging
npm run format    # rewrites files to the bsfmt.json style

Then test on a real Roku. The desktop tools don't reproduce focus, animation and playback behaviour.

Automated device tests live under tests/, with roku-webdriver and a Roku Automated Script Platform script for the sign-out flow. They need a Roku in Developer Mode on the network.

Configuration files

File	What it controls
bsconfig.json	Which files go into the channel, the linter plugin, source maps, and the staging folder
bsfmt.json	Formatting rules, enforced on contributions
bslint.json	Lint rules for @rokucommunity/bslint
manifest	The Roku channel manifest: title, version numbers, splash and icon assets, FHD resolution
package.json	The version the zip is named after, and the build, lint and format scripts

Advanced: a signed package for the Channel Store

The zip is a sideload package. The Channel Store takes a signed .pkg, which has to be signed with the same key as every earlier Moonfin release or the store treats it as a different channel. scripts/create-roku-pkg.local.sh builds and signs one on a Roku that holds that key. It reads its values from a git-ignored .env.roku file (the Roku's address, the developer password, the signing password from genkey, and the expected dev id). This step is for maintainers, a contributor never needs it.

Troubleshooting

bsc: command not found. Run the build through npm run build, which uses the project's own copy. If you ran npx bsc in a fresh checkout, run npm ci first.

The zip installs but the Roku shows an old version of my change. Check that the code is in build/staging/ and inside the zip, not only in the source file. A stale editor buffer or sync tool can revert a save between edit and build. grep for a line you just added in all three places.

Upload fails with "Install Failure: Compilation Failed". The Roku's own compiler rejected something the desktop compiler let through. Open http://<Roku IP> and read the error on the Installer page, or watch the debug console with telnet <Roku IP> 8085.

The Roku isn't found by roku-deploy. Developer Mode must be on, the address must be the one under Settings > Network > About, and the password is the developer web password, not your Roku account password.