Registry / http-networking / matter-server

matter-server

JSON →
library0.6.1jsnpmunverified

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-server
INSTALL
IMPORT
SIG · MATTER-SERVER
M
matter-server
http-networkingjavascriptv0.6.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MatterServer
import { MatterServer } from 'matter-server';
const MatterServer = require('matter-server');
The primary class for instantiating and managing the Matter WebSocket server. ESM is the preferred import style.
MatterServerOptions
import { MatterServer, type MatterServerOptions } from 'matter-server';
Type definition for configuring the MatterServer. Use 'type' import for clarity and bundler optimization.
Logger
import { Logger } from '@project-chip/matter-node.js/log';
While not directly from `matter-server`, this is the standard logging utility within the broader `matter.js` ecosystem, commonly used for server diagnostics.

This quickstart initializes and starts the `matter-server` on a specified port, demonstrating basic setup and graceful shutdown for a WebSocket Matter controller.

import { MatterServer, MatterServerOptions } from 'matter-server'; import { Logger } from '@project-chip/matter-node.js/log'; const MATTER_PORT = parseInt(process.env.MATTER_PORT ?? '5580', 10); const MATTER_SERVER_ADDRESS = process.env.MATTER_SERVER_ADDRESS ?? '0.0.0.0'; const MATTER_FRONTEND_PATH = process.env.MATTER_FRONTEND_PATH ?? undefined; async function startMatterServer() { const logger = new Logger('MatterServerQuickstart'); const serverOptions: MatterServerOptions = { port: MATTER_PORT, host: MATTER_SERVER_ADDRESS, frontendPath: MATTER_FRONTEND_PATH, // Optionally configure Matter.js backend settings here // For example, persistent storage paths, device setup, etc. }; const server = new MatterServer(serverOptions); try { logger.info(`Starting Matter WebSocket Server on ${MATTER_SERVER_ADDRESS}:${MATTER_PORT}...`); await server.start(); logger.info(`Matter WebSocket Server started successfully.`); if (!MATTER_FRONTEND_PATH) { logger.info(`Dashboard available at http://localhost:${MATTER_PORT}`); } logger.info(`WebSocket endpoint: ws://localhost:${MATTER_PORT}`); // Keep the server running until explicitly stopped process.on('SIGINT', async () => { logger.info('Shutting down Matter WebSocket Server...'); await server.close(); logger.info('Matter WebSocket Server stopped.'); process.exit(0); }); } catch (error) { logger.error(`Failed to start Matter WebSocket Server: ${error}`); process.exit(1); } } startMatterServer();
matter-server --version
Debug
Known issues
breakingThe package has strict Node.js engine requirements. Running on unsupported Node.js versions will result in startup failures.
fix
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.
affects: >=0.5.0
gotchaWhen using the built-in dashboard, if the server is not running on 'localhost' or if using a reverse proxy, you must manually specify the WebSocket server URL (e.g., `ws://homeassistant.local:5580`) in the dashboard interface.
fix
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.
affects: >=0.1.0
gotchaThe `matter-server` package relies on specific ports for its operation (default 5580). Conflicts with other services using the same port will prevent the server from starting.
fix
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.
affects: >=0.1.0
Errors
Common errors & fixes
Error: The current Node.js version is X.Y.Z, but this package requires >=20.19.0 <22.0.0 || >=22.13.0.
Unsupported Node.js version. The package enforces specific Node.js engine requirements.
fix
Update or switch your Node.js version to one supported by `matter-server` (e.g., `nvm use 20.19.0`).
Error: listen EADDRINUSE: address already in use :::5580
The default port (5580) or a configured port is already being used by another application or process.
fix
Change the server port in your `MatterServerOptions` configuration or through the `MATTER_PORT` environment variable, or terminate the conflicting process.
Error: Cannot find module 'matter-server/dist/server/MatterServer' or its corresponding type declarations.
Incorrect import path or a TypeScript configuration issue preventing module resolution, possibly due to ESM/CJS differences.
fix
Ensure you are using `import { MatterServer } from 'matter-server';` and your `tsconfig.json` `moduleResolution` is set appropriately for ESM (e.g., `bundler` or `node16`).
Upgrade
Version history
0.6.1latest on npm
Audit
Dependencies
matter.jsrequiredCore JavaScript Matter SDK on which this server is built.
@matter-server/ws-controllerrequiredProvides the core logic for the WebSocket API implementation.
@matter-server/dashboardrequiredDelivers the interactive web-based dashboard for server interaction and data visualization.
@matter-server/custom-clustersrequiredRegisters a set of community-provided custom Matter clusters.
Agent activity
2 hits · last 30 days
node
2
Resources