Contributions Welcome!

July 25, 2026 · View on GitHub

Any contributions you're willing to make are super appreciated. That includes a wide variety of things – not just code!

Types of Contributions

Since this project is still maturing, many of its initial contributions will take the form of new features or bug fixes. Even if you're not familiar with JavaScript, you can still help make the BrightScript Simulator a better tool for the community. You can:

  1. Improve documentation (even minor typos fixes are helpful!)
  2. File issues demonstrating where this implementation diverges from the reference one (i.e. on a Roku device)
  3. Use the simulator and tell your friends about it

How to Contribute

Submitting Issues

If you find something wrong with the desktop application, or something doesn't seem right, feel free to open a new issue. If the issue is related to how the simulator handles the BrightScript language and components, then you should open the issue on the brs-engine project. Please try to avoid "how do I X in BrightScript" questions however — those are best suited for StackOverflow or similar Q&A sites.

Bug Reports

When opening a bug report, please include the following:

  1. A description of the bug
  2. A BrightScript file that reproduces the issue
  3. What you expected to happen
  4. What actually happened
  5. How consistently you saw the behavior (10%? 90%? Every time?)
  6. The versions of brs-desktop and node you found the bug in
  7. Your operating system and version

Feature Requests

Have you found something that this project is missing? That's great! We'd love to hear about it. Please provide the following:

  1. A description of the new or missing feature
  2. A sample BrightScript file that uses the feature
  3. How you expect the feature to behave, or a link to the BrightScript documentation describing its behavior

Fixing Issues / Adding Features

Regardless of whether you're fixing bugs or implementing new features, there's a few things you'll want to do make the process as easy as possible:

  1. Comment on the issue and tell us that you're interested in working on it. This should lower the (admittedly rare) chances of someone stealing your that bug/feature from you :smile:.
  2. Create a fork of this repo if you haven't already
  3. Send us a pull request!

What We Look For in a Pull Request

There aren't to many mandatory things for pull requests, besides what you'd expect from any open-source project (e.g. "don't delete all the code", "don't delete a user's home directory at runtime"). The most important project-specific "must-haves" that we'll look for that are:

  1. Pull requests should be based on a pretty recent version of the master branch, to minimize merge conflicts.
  2. Please include tests, and run npm test before opening the pull request. A bug fix should come with a test that fails before the fix and passes after it. CI runs the same command on macOS, Ubuntu and Windows, and the build job will not start until it passes.

Running the Tests

npm ci                 # or npm install
npm test               # run everything once
npm run test:watch     # re-run affected tests as you edit
npm run test:coverage  # coverage report into coverage/

Tests use Vitest. Electron itself is never launched: vitest.config.mjs maps electron and a handful of Electron-dependent packages to stubs in test/mocks/, so the suite runs headless and needs no display.

Where new tests belong:

  • Pure logic goes in test/unit/, mirroring the path of the file under test (src/helpers/util.js → test/unit/helpers/util.spec.js).
  • Anything needing a live socket goes in test/integration/. Use the getFreePort() helper rather than the default port from src/constants.js, so spec files can run concurrently without colliding.

There is no end-to-end layer, so changes to windows, menus or anything visual still need to be checked by running the app with npm run start.