The `matter-server` package implements a comprehensive Matter Controller Server over WebSockets, leveraging the JavaScript Matter SDK `matter.js` as its foundational layer. It currently stands at stable version `0.6.1`, with a development cadence that includes frequent nightly alpha releases alongside regular official updates, indicating active and continuous development. This project differentiates itself by providing a full-fledged web server, a WebSocket endpoint that adheres to the Open Home Foundation (OHF) Matter Server API (with logic encapsulated in `@matter-server/ws-controller`), and an interactive dashboard (powered by `@matter-server/dashboard`). It also integrates community-provided custom Matter clusters via `@matter-server/custom-clusters` and ensures backward compatibility with the OHF Python Matter Server, facilitating migration and interoperability for existing users. Client applications can connect using the companion `@matter-server/ws-client` library. The server is designed for modern Node.js environments, specifically requiring Node.js versions `>=20.19.0 <22.0.0` or `>=22.13.0`.
npm install matter-serverVerified import paths — ran on the pinned version, not inferred.
This quickstart initializes and starts the `matter-server` on a specified port, demonstrating basic setup and graceful shutdown for a WebSocket Matter controller.
Ensure your Node.js environment is within the supported range: `>=20.19.0 <22.0.0 || >=22.13.0`. Use nvm or a similar tool to manage Node.js versions.
Access the dashboard at `http://localhost:PORT` and enter the correct WebSocket URL when prompted, or configure network settings if running within a Home Assistant add-on.
Ensure the configured port is free, or specify an alternative port in the `MatterServerOptions` (e.g., `port: 5581`) or via the `MATTER_PORT` environment variable.
Update or switch your Node.js version to one supported by `matter-server` (e.g., `nvm use 20.19.0`).
Change the server port in your `MatterServerOptions` configuration or through the `MATTER_PORT` environment variable, or terminate the conflicting process.
Ensure you are using `import { MatterServer } from 'matter-server';` and your `tsconfig.json` `moduleResolution` is set appropriately for ESM (e.g., `bundler` or `node16`).