Dev guide

This guide gets JellyRock’s source code running on your own Roku. With it set up, you can change the code, try a build before it is released, and send the developers logs when you hit a bug.

Developer mode

Put your Roku in developer mode. Write down your Roku’s IP address and the password you create, because the steps below ask for both.

Get the code

Clone the repository, then open its folder:

git clone https://github.com/jellyrock/jellyrock.git
cd jellyrock

Install dependencies

You need node 22 (22.22.1 or later), 24, or 26 and later. Then install the dependencies:

npm install

Method 1: Visual Studio Code

We recommend Visual Studio Code for this project. Its BrightScript Language extension checks your code as you type, and lets you set breakpoints, inspect variables while the app runs, format code and drive the Roku from the editor. See its feature list for more.

Set up Visual Studio Code

1. Install Visual Studio Code.
2. Install the BrightScript Language extension from the Extensions panel, or from the Marketplace.
3. Install the other extensions the workspace recommends (listed in .vscode/extensions.json). If you edit JavaScript or JSON, Prettier and ESLint matter most: the workspace formats those files with Prettier on save, as the pre-commit hook does.

Run the app

1. Open the jellyrock folder in Visual Studio Code.
2. Press F5, or choose Run → Start Debugging.
3. When asked, enter your Roku’s IP address and developer password.

Visual Studio Code builds the app, installs it on your Roku and starts it.

F5 first takes the device lock, so a test run in a terminal can’t install over your session, and yours can’t install over a run already going. If another run holds the Roku, F5 stops before the build and Problems names the run: wait for it, or use another Roku. Visual Studio Code may first ask whether to debug anyway; choose Abort or Show Errors, since Debug Anyway installs over the other run. The lock is released when you stop the session. Taking it needs a gh login and your Roku’s address saved in your settings (next section); without either, F5 runs without the lock and says so in its terminal.

Save your Roku’s address and password

By default the extension asks for the Roku and its password on every run. To skip that, set them in your Visual Studio Code user settings:

{
  "brightscript.debug.host": "YOUR_ROKU_HOST_HERE",
  "brightscript.debug.password": "YOUR_ROKU_DEV_PASSWORD_HERE"
}

Put them in your user settings, not in .vscode/launch.json, so your password stays out of the repository. The saved address is also the Roku F5 locks.

Method 2: Command line

You need make and curl.

Install on your Roku

Tell make which Roku to use, with the IP address and password from developer mode:

export ROKU_DEV_TARGET=192.168.1.234
export ROKU_DEV_PASSWORD=password

Then build the app, install it and start it:

make build-dev install

Run this after every change. Plain make install installs whatever is already in out/jellyrock.zip, so it skips your latest changes once a build exists.

If you only want to run the latest code, not change it, you need to install once. The app stays on your Roku after a restart.

Bug/crash reports

When the app crashes or misbehaves, open the Roku’s debug log to see what went wrong:

telnet ${ROKU_DEV_TARGET} 8085

To leave telnet, press Ctrl + ], then type quit and press Enter.

To add a picture of the screen to your report, take a screenshot. It is saved as screenshot.jpg in the project folder:

make screenshot

Then open an issue with the log and the screenshot.

Committing

Git hooks check your work, so you rarely need to run the linters yourself. Before each commit, the pre-commit hook formats, lints and spell-checks the files you staged. Before each push, the pre-push hook runs the checks that need the whole project (the BrighterScript compile and lint, the docs checks and the script tests) for the files in the push. It also regenerates the translation keys and the index of these dev guides, and commits them for you. CI runs the same checks on every pull request.

To debug one failure before you push, run that check’s script, for example npm run lint:translations, rather than the whole npm run lint.