JavaScript/TypeScript based Matter Implementation

What is Matter?

Matter is a new secure, reliable and local standard protocol for smart/IoT devices launched at the end of 2022 by the Connectivity Standards Alliance.

To learn more about Matter visit https://csa-iot.org/all-solutions/matter/

What is matter.js?

matter.js is a TypeScript/JavaScript implementation of the complete Matter protocol.

Our main goal is to create a robust and compliant library that enables the seamless implementation of Matter-compatible devices, bridges, controllers, and a shell application. This effort is dedicated to improving Matter's accessibility for testers, smart home enthusiasts, and developers of OS-based IoT products. Fostering a second implementation of the Matter standard, aligned with the same specifications, not only expands the ecosystem but also contributes to the validation and increased robustness of the standard itself.

[!IMPORTANT] matter.js as library, along with all related tools (such as the Shell app) and examples, is not certified by the Connectivity Standards Alliance (CSA). They are provided solely to demonstrate the capabilities of our solution and to support testing and development. Using matter.js does not certify your product — Connectivity Standards Alliance membership and product certification are required to release official Matter devices. For more details, see A note on certification for more details.

matter.js consists of a set of pure JavaScript base packages without any native dependencies, implementing the Matter protocol and required interfaces in JavaScript, along with extensive typings for The Matter standard and the matter.js APIs. Further packages with Node.js based native dependencies utilize the base package to implement platform-specific parts using Node.js for networking and other necessary native features or add BLE support. Node.js example scripts implement example CLI scripts for devices, bridges or controllers. A Matter Shell allows interaction with Matter devices as a controller via a CLI interface.

To use matter.js in your own non-Node.js based projects you need to implement the platform specific parts. See Using matter.js in unsupported JavaScript environments for more details. If you do this, please contact us to add your platform to the list of supported platforms.

matter.js employs code generation to ensure a comprehensive model of all Matter Clusters and (soon) device types. This includes typing and documentation, readily available within developers' IDEs, facilitating easy accessibility and adherence to conformance information during coding. This approach allows for easy addition of new clusters and device types, ensuring synchronization with the Matter standard.

How is matter.js used?

matter.js serves various purposes and is employed for:

• Building (commercial) Matter devices and bridges:<br>Use JavaScript/TypeScript to create Matter devices or bridges for OS-based IoT products. The extensive typing information and documentation facilitate the easy implementation of required functionality while ensuring synchronization with the Matter specification. If you plan to certify a device based on matter.js please see note below.

• Building Matter controllers:<br>Develop Matter controllers with JavaScript/TypeScript for OS-based IoT products. Post-commissioning (including BLE support), controllers can access all data from devices and control them. The API supports development with known typings of all clusters when endpoints and device types are known during development. It also allows generic programmatic access to all clusters and attributes. Typing information of custom clusters can be added to the controller or accessed generically with generic data parsing support. If you plan to build/certify a controller based on matter.js please see note below.

• Rapid prototyping for test and development:<br>Enable rapid development of device or controller prototypes for testing and development purposes. JavaScript's nature and the convenient matter.js API make it easy to create prototypes. Testing different feature combinations or endpoint structures can be done quickly using JavaScript testing frameworks.

• Ad-hoc testing of Matter devices using the matter.js shell:<br>Employ the Matter Shell application as a controller to interact with Matter devices via a CLI interface. Ideal for manual testing and development purposes.

Explore the versatile capabilities of matter.js and adapt it to your specific use cases!

A note on certification

To release a Matter product (device, bridge, or controller), you must be a member of the Connectivity Standards Alliance (CSA) and obtain certification for your product. This requirement is independent of the implementation you use and is what also allows you to use the Matter name and logo on your product and in marketing.

matter.js itself is not certified by the Connectivity Standards Alliance, and using matter.js does not automatically certify your product. While we ensure that the protocol and default cluster implementations we provide align with the Matter Specification, certification of your final product remains your responsibility.

Please refer to the Certification sections on the Matter Handbook and the Connectivity Standards Alliance Homepage for more details on the certification process and benefits.

If you plan to officially certify a device, bridge, or controller based on matter.js, please contact us via email or Discord to get the latest information on matter.js compliance status, supported and pending features, and guidance on the certification process. We can also support you during certification if needed.

matter.js has already been successfully used in certified products, but there are still important considerations and discussions required when planning certification.

JavaScript/Node.js compatibility

• At least ES2022 needs to be used as build target for your project!
• The published packages are supports all LTS Node.js versions starting with 20.x

Please also see the additional TypeScript notes.

How to use matter.js

Create a new project based on matter.js

We provide templates for various matter.js use cases. You can bootstrap a new project in Node.js using npm init:

npm init @matter

For details on available templates and other options:

npm init @matter help

Add matter.js to an existing project

To use matter.js you import @matter/main as a dependency in your project. This package re-exports functionality from other packages, so it is not necessary to have multiple dependencies. If you need BLE support you can use @matter/nodejs-ble as an additional dependency.

npm install @matter/main --save

If your project is not based on Node.js you need to implement the platform specific parts. See Using matter.js in unsupported JavaScript environments for more details.

Run the examples

The templates we use when you bootstrap a new application are available as examples you can run directly. You can install them in Node.js as follows:

npm install @matter/examples

Please refer to the Examples readme for information regarding their usage: examples

Extending and contributing to matter.js

We welcome contributions! If you have Node.js installed, prepare your development environment as follows:

git clone https://github.com/matter-js/matter.js
cd matter.js
npm install

This will install all dependencies and create symlinks between the packages, so that it can be used locally. It also builds all packages.

On Windows, in order to successfully build all the packages (tested on Windows 11 Pro) make sure to have installed Node.js 20+, the windows-build-tools and node-gyp version 10. On Non-Windows platforms and having Python 3.12+ installed, please also make sure to use npm 10.2.3+.

Connecting with the community

If you have issues please use the GitHub "Issues" of this repository. For questions or idea discussions please use the "Discussions" in this GitHub repository.

Additionally, our "Matter Integrators" Discord server is a great place to discuss matter.js, the Matter protocol and how to implement Matter in various environments -- not just JavaScript/TypeScript! You can join it here: https://discord.gg/ujmRNrhDuW .

Compatibility with the Matter standard

See here.

Compatibility with popular ecosystems

Devices created with matter.js/matter-node.js have been tested with:

• Apple iOS (iPhone or iPad) and tvOS 16 (Apple TV) - "Home" app by Apple: Fully working
• Google Home Ecosystem (Android or Google Nest smart speakers/display) - "Google Home" app: Fully working
• Amazon Alexa (Amazon Echo smart speakers/displays) : Fully working
• Tuya Smart (SmartLife) app: Fully working
• Samsung SmartThings (Station or Hub v2 and later): Fully working
• LG ThinQ: Fully working, beside glitches in LG software sometimes
• Homey Pro: Fully working
• Home Assistant - Matter integration: Fully working
• OpenHAB - Matter Binding: Fully working (openH