Matter.js WebSocket Server

Common errors

• Error: The current Node.js version is X.Y.Z, but this package requires >=20.19.0 <22.0.0 || >=22.13.0.

  cause 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

  cause 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.

  cause 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`).

Warnings

• breaking The 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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install matter-server npm
• yarn add matter-server yarn
• pnpm add matter-server pnpm

Imports

• MatterServer
  wrong:

  const MatterServer = require('matter-server');

  correct:

  import { MatterServer } from '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.

Quickstart

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();