Setting up a Developer Environment
Companion is written in Javascript/Typescript and uses the Node.js runtime. In addition, all parts of Companion are organized and tracked using Git. Here we will provide instructions for installing the development tools you will need for contributing to Companion, whether as a module or a part of core Companion.
Companion, Javascript and Node.js are platform independent, so you can develop on Windows, macOS or Linux and the code you write will be able to run on all three platforms.
For module development you may be able to skip step 5, below, "Enabling USB on Unix". Instead simply install Companion according to the instructions in the getting started guide.
1. Install Node.js manager (fnm)
We strongly recommend using the fnm version manager to allow for easily updating and switching between Node.js versions. If you choose to install Node.js without fnm, you will still need to ensure you a running the right Node.js versions as Companion evolves.
Installing fnm on Windows
If you want to run in Linux Subsystem for Windows (aka WSL), please follow the WSL Instructions page and then follow the instructions, below, in the Linux section, below.
If PowerShell complains about unsigned apps, go to Settings, search for "developer settings" and enable "Change execution policy to allow local PowerShell scripts to run without signing". Alternatively, in a PowerShell with elevated permissions run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
If you are new to code development on Windows, the built-in winget command is probably the simplest way to install fnm. (Other popular package managers such as Chocolatey and Scoop work similarly.)
In Powershell (admin mode) type:
winget install Schniz.fnm
Once it has loaded, configure PowerShell as described in the fnm GitHub repo. Briefly you need to add a line to the end of the powershell startup script (aka profile). The following opens the profile file in a text editor
if (-not (Test-Path $profile)) { New-Item $profile -Force }
Invoke-Item $profile
...put the following line at the end of the file:
fnm env --use-on-cd --corepack-enabled --version-file-strategy=recursive --shell powershell | Out-String | Invoke-Expression
Installing fnm on Linux and MacOS
Use the following script (see fnm instructions in GitHub)
curl -fsSL https://fnm.vercel.app/install | bash
The install script requires unzip to be installed on your system. If it isn't, install it by typing:
sudo apt install unzip
upgrading fnm:
on MacOS upgrade fnm using Homebrew: brew upgrade fnm (you can also install using manually using Homebrew)
on other Linux systems upgrade using:
curl -fsSL https://fnm.vercel.app/install | bash -s -- --skip-shell
2. Install Node.js using fnm
Once you have installed fnm, execute the following in a terminal/PowerShell. To install Node.js v22 (the version required for Core Companion development at the time of writing) and make it the default.
fnm install 22
fnm use 22
fnm default 22
corepack enable
(Note: corepack enable may not be needed in Windows if using PowerShell with the setup described above.)
Some older modules uses node v18 instead of v22, but are encouraged to update to v22. Sometimes updating the node version can introduce new bugs, but staying on older versions makes development harder as tools drop support for those versions. At some point, Companion will require modules to be node v22 (or perhaps a newer version).
With fnm you can install both v18 and v22 and quickly switch between versions as needed. fnm can be setup to do this automatically with the --use-on-cd switch (as recommended in the Windows section above), or you can switch it manually with a command like fnm use 22. See the fnm config docs for more information on --use-on-cd and the related --resolve-engines options.
Do not install yarn directly. Instead, let corepack ensure that the right version is installed
when you run yarn install. If you have already installed
yarn globally and are having problems, consider removing the global install.
3. Install and setup git
See the instructions for installing Git here.
As per the windows note here:
In order for git clone to give you lf endings, this default needs to be overridden before you clone the companion repository. In a git bash window type:
git config set --global core.autocrlf false
git config set --global core.eol lf
4. Enabling USB access on Linux Systems
If you are using linux, you should follow the dependencies and udev rules steps as described in the README included in the release builds https://github.com/bitfocus/companion/tree/main/assets/linux.
For WSL, follow the WSL setup instructions instead.
5. Editing Code / Integrated Development Environment (IDE)
To edit the source code or write new code you can use any text editor you like, but there are many editors which are made especially for developing computer code or even better especially for JavaScript. If you have no prior experience, we recommend the Visual Studio Code editor (VS Code).
We recommend installing the ESLint, prettier and typos plugins for VS Code.
If you want a simple windowing text-editor in Linux, you can try gedit. Install it with sudo apt install gedit