This repository provides a default template for developing Matterbridge plugins.
If you like this project and find it useful, please consider giving it a star on GitHub at Matterbridge Plugin Template and sponsoring it.
- Dev Container support for instant development environment.
- Pre-configured TypeScript, ESLint, Prettier, Jest and Vitest.
- Example project structure for Accessory and Dynamic platforms.
- Ready for customization for your own plugin.
- The project has an already configured Jest / Vitest test unit (with 100% coverage) that you can expand while you add your own plugin logic.
The project has the following already configured workflows:
- build-matterbridge-plugin.yml: run on push and pull request and build, lint and test the plugin on node 20, 22 and 24 with ubuntu, macOS and windows.
- publish-matterbridge-plugin.yml: publish on npm when you create a new release in GitHub. Add your NPM_TOKEN to the repository secrets.
- publish-matterbridge-plugin-dev-daily-from-dev.yml: publish a dev on npm from main branch every day at midnight UTC if there is a new commit. Add your NPM_TOKEN to the repository secrets.
- publish-matterbridge-plugin-dev-daily-from-main.yml: publish a dev on npm from dev branch every day at midnight UTC if there is a new commit. Add your NPM_TOKEN to the repository secrets.
- codeql.yml: run CodeQL from the main branch on each push and pull request.
- codecov.yml: run CodeCov from the main branch on each push and pull request. You need a codecov account and add your CODECOV_TOKEN to the repository secrets.
Important: If you plan to use this template in a private repository, be aware that GitHub Actions usage may incur costs:
- Free tier limits: Private repositories have limited free GitHub Actions minutes per month (2,000 minutes for free accounts).
- Workflow intensity: This template includes multiple workflows that run on different operating systems (Ubuntu, macOS, Windows) and Node.js versions (20, 22, 24), which can consume minutes quickly.
- Daily automated workflows: The dev publishing workflows run daily, which can add up over time.
- Pricing varies by OS: macOS runners cost 10x more than Ubuntu runners, Windows runners cost 2x more.
Recommendations for private repos:
- Monitor your GitHub Actions usage in your account settings.
- Consider disabling some workflows or reducing the OS/Node.js version matrix.
- Review GitHub's pricing for Actions to understand costs.
- For public repositories, GitHub Actions are free with generous limits.
- Create a repository from this template using the template feature of GitHub.
- Clone it locally and open the cloned folder project with VS Code. If you have docker or docker desktop, just run
code .. - When prompted, reopen in the devcontainer. VS Code will automatically build and start the development environment with all dependencies installed.
- Update the code and configuration files as needed for your plugin. Change the name (keep always matterbridge- at the beginning of the name), version, description, author, homepage, repository, bugs and funding in the package.json.
- Follow the instructions in the matterbridge README-DEV and comments in module.ts to implement your plugin logic.
- Docker Desktop or Docker Engine are required to use the Dev Container.
- Devcontainer works correctly on Linux, macOS, Windows, WSL2.
- The devcontainer provides Node.js, npm, TypeScript, ESLint, Prettier, Jest, Vitest and other tools and extensions pre-installed and configured.
- The dev branch of Matterbridge is already build and installed into the Dev Container and linked to the plugin.
- The devcontainer is optimized using named mounts for node_modules and matterbridge.
- You can run, build, and test your plugin directly inside the container.
- To open a terminal in the devcontainer, use the VS Code terminal after the container starts.
- All commands (npm, tsc, matterbridge etc.) will run inside the container environment.
- All the source files are on host.
- Since the dev container doesn't have network host and IPV6, is not possible to pair matterbridge from the Devcontainer but you can add your plugin to matterbridge and test it inside the devcontainer.
When you want to test your plugin with a paired controller, you have several options:
- create a tgz (npm run npmPack) and upload it to a running instance of matterbridge.
- publish it with tag dev and install it (matterbridge-yourplugin@dev in Install plugins) in a running instance of matterbridge.
- use a local instance of matterbridge running outside the dev container and install (../matterbridge-yourplugin in Install plugins) or add (../matterbridge-yourplugin in Install plugins) your plugin to it (easiest way). Adjust the path if matterbridge dir and your plugin dir are not in the same parent directory.
Refer to the Matterbridge documentation for other guidelines.