Matterbridge Test Plugin

2.0.15 · active · verified Tue Apr 21

The `matterbridge-test` package serves as a development and demonstration plugin within the `Matterbridge` ecosystem, a platform designed to bridge various smart home protocols like Matter and Homebridge for unified IoT device control. As of April 2026, its current stable version is 2.0.15. The package exhibits an active release cadence, with frequent patch updates primarily focused on dependency management, internal tooling improvements, and developer experience enhancements. It is not intended for direct end-user functionality but rather provides a reference implementation or testing ground for plugin development within the Matterbridge framework, ensuring compatibility and illustrating integration patterns. A key differentiator is its role in validating the Matterbridge plugin API and its strong adherence to modern TypeScript practices, as evidenced by its included type definitions and strict Node.js engine requirements, facilitating type-safe development for other Matterbridge plugin authors.

Common errors

```
Error: The package 'matterbridge-test' requires Node.js version X.X.X. Your current Node.js version is Y.Y.Y.
```
cause The installed Node.js version does not satisfy the `engines` requirement specified in `package.json`.

fix Upgrade or downgrade your Node.js environment to a compatible version (e.g., `>=20.19.0 <21.0.0`) using a Node.js version manager like `nvm` (`nvm install X.X.X && nvm use X.X.X`).
```
TypeError: matterbridge.registerPlugin is not a function
```
cause The `registerPlugin` method or the `matterbridge` instance itself is not correctly initialized or configured according to the `Matterbridge` framework's API.

fix Refer to the official `Matterbridge` documentation for the correct way to instantiate the `Matterbridge` core and register plugins. Ensure all necessary setup steps are completed before attempting to register your plugin.
```
ERR_PACKAGE_PATH_NOT_EXPORTED (or similar CommonJS `require()` error)
```
cause Attempting to use CommonJS `require()` syntax with `matterbridge-test`, which is likely an ESM-only module, or trying to access an unexported subpath.

fix Ensure your project is configured for ECMAScript Modules (ESM) by adding `"type": "module"` to your `package.json` and use `import` statements (e.g., `import { TestPlugin } from 'matterbridge-test';`).

Warnings

breaking The package has very strict Node.js engine compatibility requirements, specifying narrow ranges for versions 20, 22, and 24. Running with an unsupported Node.js version will prevent the package from loading or functioning correctly.
Fix: Ensure your Node.js environment strictly matches one of the specified versions: `>=20.19.0 <21.0.0`, `>=22.13.0 <23.0.0`, or `>=24.0.0 <25.0.0`. Use a version manager like `nvm` or `fnm` to easily switch versions.
gotcha While the changelog primarily details internal dependency updates and developer environment enhancements, there are no explicit breaking change notices for consumers of the `matterbridge-test` plugin's API in recent versions. Users should monitor for potential indirect breaking changes if Matterbridge's core plugin API evolves rapidly, especially considering the frequent major version bumps in underlying dependencies like `eslint` and `typescript`.
Fix: Regularly review the `matterbridge` and `matterbridge-test` changelogs when upgrading to detect any subtle behavioral changes. Test your plugin integrations thoroughly after updates.

Install

npm install matterbridge-test npm
yarn add matterbridge-test yarn
pnpm add matterbridge-test pnpm

Imports

TestPlugin

wrong:

const TestPlugin = require('matterbridge-test').TestPlugin;

correct:

import { TestPlugin } from 'matterbridge-test';

The package ships with TypeScript types and is primarily used with ESM imports.

TestPluginOptions

wrong:

import { type TestPluginOptions } from 'matterbridge-test/dist/plugin';

correct:

import { TestPluginOptions } from 'matterbridge-test';

Imports the TypeScript interface for plugin configuration options.

Quickstart

Demonstrates how to register and initialize the `Matterbridge Test Plugin` within a hypothetical `Matterbridge` instance, including basic configuration, and simulates a graceful shutdown.

import { Matterbridge } from 'matterbridge'; // Assuming 'matterbridge' is the core framework
import { TestPlugin, TestPluginOptions } from 'matterbridge-test';

async function main() {
  // Initialize Matterbridge core (hypothetical instance)
  // In a real scenario, configuration might be loaded from a file or environment.
  const matterbridge = new Matterbridge({
    logLevel: 'debug' // Example Matterbridge core configuration
  });

  // Define configuration for the TestPlugin. This structure is defined by TestPluginOptions.
  const pluginConfig: TestPluginOptions = {
    name: "MyTestPluginInstance",
    testSetting: "exampleValue", // Placeholder for a setting specific to TestPlugin
    // Add other settings as required by TestPluginOptions
  };

  // Register the TestPlugin with the Matterbridge instance.
  // The exact registration API might vary based on the 'matterbridge' framework version.
  console.log(`Registering TestPlugin with config:`, pluginConfig);
  matterbridge.registerPlugin(TestPlugin, pluginConfig);

  // Start the Matterbridge instance, which will initialize and run the registered plugin(s).
  await matterbridge.start();
  console.log("Matterbridge started successfully with Matterbridge Test Plugin.");

  // For a test or demonstration plugin, you might set up a timeout to gracefully shut down
  // or perform specific test actions.
  setTimeout(async () => {
    console.log("Simulating graceful shutdown after 30 seconds...");
    await matterbridge.stop();
    console.log("Matterbridge stopped.");
    process.exit(0);
  }, 30000); // Stop after 30 seconds for demonstration
}

main().catch(err => {
  console.error("An error occurred during Matterbridge operation:", err);
  process.exit(1);
});

view raw JSON →