{"id":11272,"library":"matter-server","title":"Matter.js WebSocket Server","description":"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`.","status":"active","version":"0.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/matter-js/matterjs-server","tags":["javascript","typescript"],"install":[{"cmd":"npm install matter-server","lang":"bash","label":"npm"},{"cmd":"yarn add matter-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add matter-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core JavaScript Matter SDK on which this server is built.","package":"matter.js"},{"reason":"Provides the core logic for the WebSocket API implementation.","package":"@matter-server/ws-controller"},{"reason":"Delivers the interactive web-based dashboard for server interaction and data visualization.","package":"@matter-server/dashboard"},{"reason":"Registers a set of community-provided custom Matter clusters.","package":"@matter-server/custom-clusters"}],"imports":[{"note":"The primary class for instantiating and managing the Matter WebSocket server. ESM is the preferred import style.","wrong":"const MatterServer = require('matter-server');","symbol":"MatterServer","correct":"import { MatterServer } from 'matter-server';"},{"note":"Type definition for configuring the MatterServer. Use 'type' import for clarity and bundler optimization.","symbol":"MatterServerOptions","correct":"import { MatterServer, type MatterServerOptions } from 'matter-server';"},{"note":"While not directly from `matter-server`, this is the standard logging utility within the broader `matter.js` ecosystem, commonly used for server diagnostics.","symbol":"Logger","correct":"import { Logger } from '@project-chip/matter-node.js/log';"}],"quickstart":{"code":"import { MatterServer, MatterServerOptions } from 'matter-server';\nimport { Logger } from '@project-chip/matter-node.js/log';\n\nconst MATTER_PORT = parseInt(process.env.MATTER_PORT ?? '5580', 10);\nconst MATTER_SERVER_ADDRESS = process.env.MATTER_SERVER_ADDRESS ?? '0.0.0.0';\nconst MATTER_FRONTEND_PATH = process.env.MATTER_FRONTEND_PATH ?? undefined;\n\nasync function startMatterServer() {\n  const logger = new Logger('MatterServerQuickstart');\n\n  const serverOptions: MatterServerOptions = {\n    port: MATTER_PORT,\n    host: MATTER_SERVER_ADDRESS,\n    frontendPath: MATTER_FRONTEND_PATH,\n    // Optionally configure Matter.js backend settings here\n    // For example, persistent storage paths, device setup, etc.\n  };\n\n  const server = new MatterServer(serverOptions);\n\n  try {\n    logger.info(`Starting Matter WebSocket Server on ${MATTER_SERVER_ADDRESS}:${MATTER_PORT}...`);\n    await server.start();\n    logger.info(`Matter WebSocket Server started successfully.`);\n    if (!MATTER_FRONTEND_PATH) {\n        logger.info(`Dashboard available at http://localhost:${MATTER_PORT}`);\n    }\n    logger.info(`WebSocket endpoint: ws://localhost:${MATTER_PORT}`);\n\n    // Keep the server running until explicitly stopped\n    process.on('SIGINT', async () => {\n      logger.info('Shutting down Matter WebSocket Server...');\n      await server.close();\n      logger.info('Matter WebSocket Server stopped.');\n      process.exit(0);\n    });\n\n  } catch (error) {\n    logger.error(`Failed to start Matter WebSocket Server: ${error}`);\n    process.exit(1);\n  }\n}\n\nstartMatterServer();\n","lang":"typescript","description":"This quickstart initializes and starts the `matter-server` on a specified port, demonstrating basic setup and graceful shutdown for a WebSocket Matter controller."},"warnings":[{"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.","message":"The package has strict Node.js engine requirements. Running on unsupported Node.js versions will result in startup failures.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update or switch your Node.js version to one supported by `matter-server` (e.g., `nvm use 20.19.0`).","cause":"Unsupported Node.js version. The package enforces specific Node.js engine requirements.","error":"Error: The current Node.js version is X.Y.Z, but this package requires >=20.19.0 <22.0.0 || >=22.13.0."},{"fix":"Change the server port in your `MatterServerOptions` configuration or through the `MATTER_PORT` environment variable, or terminate the conflicting process.","cause":"The default port (5580) or a configured port is already being used by another application or process.","error":"Error: listen EADDRINUSE: address already in use :::5580"},{"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`).","cause":"Incorrect import path or a TypeScript configuration issue preventing module resolution, possibly due to ESM/CJS differences.","error":"Error: Cannot find module 'matter-server/dist/server/MatterServer' or its corresponding type declarations."}],"ecosystem":"npm"}