Release 0.13 from 28.04.2025

[Apollon77]

matter.js 0.13 – Welcome Matter 1.4

We’re excited to announce the release of version 0.13 of matter.js, the Matter JavaScript SDK!

What’s new in Version 0.13

This release primarily focuses on upgrading the supported Matter version to 1.4.0, while also delivering numerous optimizations for stability and reliability. It also removes the long-deprecated legacy Device-Building API in favor of the new, modernized approach.

matter.js v0.13 now supports all new device types, clusters, and data types introduced in the Matter 1.4 specification. In addition, we’ve added or enhanced default implementations for several clusters and added required new Matter protocol features. A highlight of this release is the full support for mechanisms to prevent attribute change over-reporting — one of the most important improvements in Matter 1.4, in our view. With new examples, such as a vacuum cleaner device, we also demonstrate how clusters must interact to support more complex device types.

The Controller implementation and API have been enhanced with new features, making them more flexible based on valuable feedback from developers.
Beyond running the full suite of Matter SDK certification tests for devices built with matter.js, we’ve introduced automated testing for the matter.js Controller implementation, validating it against both matter.js and Matter-SDK devices.

Last but not least, this new version includes many optimizations aimed at improving stability and reliability across UDP and BLE communications, persistence, and the Matter protocol stack.

Looking ahead, we plan to focus on performance and memory usage improvements, expanding support for some missing Matter protocol features, and introducing a brand-new Controller API. Stay tuned — there’s much more to come!

Breaking changes

First, the regenerated models and code for clusters and device types may include breaking changes in names, constraints, and related areas. Please review the changelog carefully, as there are notable adjustments, particularly in the Color Control and Occupancy Sensing clusters.

Additionally, the OnOff and Level Control clusters in matter.js, which previously had some features automatically enabled, have been updated. In these clusters, the transition logic and extension APIs have been enhanced to support the new “quieter” quality modes and to allow greater flexibility in transitioning attribute values.

The legacy Device-Building API, which was replaced by the new API in version 0.8, has now been fully removed. As part of this, the main Storage class has switched to the asynchronous (Async) variant, and the no longer needed re-exports from @project-chip/matter.js, and other packages under the @project-chip npm scope, have been cleaned up.
Please use @project-chip/matter.js only if you are implementing a Controller — for all other use cases, continue to use @matter/main.

The Controller implementation also includes some API method signature changes to further clean up and streamline the API.

Get Involved

Update to matter.js 0.13 on npm, and share your experiences, feedback, and questions with us on GitHub or Discord — we’re happy to help!

For a complete list of changes, see the Release Notes below.

Changelog

• IMPORTANT: This release upgrades Matter support from Matter 1.3 to the latest release, Matter 1.4.0. This includes BREAKING CHANGES in a number of areas due to specification changes. For the most part these changes are transparent because they involve low-level APIs, implicit type names, or Matter features that were never adopted elsewhere. However, some small code changes may be necessary depending on how you use Matter.js or when Datatypes or elements got renamed.

  • Especially please note that colorTempPhysicalMinMireds and colorTempPhysicalMaxMireds now need to be set when using ColorControl because the former unrealistic default values were removed from the specification. Please set proper values for your device Hint: realistic color temperature Mireds values are usually roughly between 150 (6500K) and 500 (2000K).
  • Also note the new cluster revision 5 for the OccupancySensing cluster which requires you to use feature flags, and also some attributes have changed behavior or got deprecated. We added logic that automatically fills the attributes occupancySensorTypeBitmap and occupancySensorType with the values according to the enabled features if needed.

• chip-testing

  • Feature: Added Chip-Tool compatible WebSocket Controller implementation to also run interop tests with matter.js controller
  • Feature: Added Docker based own Test Runner and execute all tests there too with chip-tool against matter.js test device

• @matter/examples

  • Enhancement: Added Robotic Vacuum Cleaner example to show the cluster dependencies and basic logic requirements
  • Enhancement: Added Air Quality Sensor example

• @matter/general

  • Breaking: Logger.logger is replaced with Logger.destinations. Properties of individual destinations are slightly different. A deprecated compatibility API should make this largely transparent
  • Feature: Logging destinations may process Diagnostic.Message directly and bypass matter.js's formatting
  • Feature: Log formatting is now extensible with custom formats
  • Feature: QuietObservable is an extended event source that emits events at reduced frequency based on configuration
  • Enhancement: Formalized concept of a logging "destination" and converted API for managing destinations to a simple object interface
  • Enhancement: Modifying log levels and format using the Logger static interface now updates defaults and applies changes to all destinations
  • Enhancement: Transaction participants no longer need implement commit-related methods if they do not participate in persistence
  • Enhancement: Missing IPv4 addresses on network interfaces are now ignored even if IPv4 is not disabled via configuration
  • Fix: Correctly handle MDNS records without QNames

• @matter/main

  • Feature: Automatically handle basicInformation uniqueId Property as defined by specification if not set by the developer

• @matter/node

  • Breaking: The Default OnOffServer implementation no longer has the "Lighting" feature enabled by default! Please enable manually when the relevant device type where the cluster is used in requires it or use the Requirement-classes like OnOffLightRequirements.OnOffServer to get the correct features enabled automatically.
  • Breaking: The Default LevelControlServer implementation no longer has the "OnOff" feature enabled by default! Please enable manually when the relevant device type where the cluster is used in requires it or use the Requirement-classes like DimmedLightRequirements.LevelControlServer to get the correct features enabled automatically.
  • Breaking: LevelControlServer API has a few small changes that may affect device implementors. Most notably the setLevel method is replaced with transition which handles both immediate and gradual level shifts
  • Breaking: Removed Implementation Logic for the "AbsolutePosition" Feature in WindowCovering default implementation because this is a forbidden (Zigbee) Feature anyway that no-one should use!
  • Breaking: The DoorLock cluster attribute supportedOperatingModes bitmap requires to clear bits for supported modes. To allow to set this bitmap correctly we added a helper bit-range alwaysSet (with value 2047) to set the unused bits. Please make sure to set the correct bits for your device according to the specification meaning.
  • Breaking: All default implementations now are async (as before if needed) or expose as MaybePromise to allow async or sync overriding. Ideally this does not change anything for custom implementations but check for returned promises when calling "super" methods.
  • Feature: Transitions utility class offers a flexible API for implementing Matter attributes that change gradually at a constant rate
  • Feature: Attributes marked as Q (quieter) quality now support an extended quiet property that controls how often and when they emit. By default Q attributes emit once per second
  • Feature: LevelControlServer and ColorControlServer performs smoother transitions with configurable transition step sizes and Matter 1.4-compliant event emitting. It offers several new extension points for integrating with hardware and bridged devices
  • Feature: Added support for the ActionSwitch feature for the SwitchServer default implementation
  • Feature: Added basic validation for all ModeBase derived *Mode clusters
  • Feature: Added basic validation for OperationalState and derived *OperationalState clusters
  • Feature: Added basic validation and logic for ServiceArea cluster
  • Enhancement: OccupancySensingServer is automatically filling some legacy attributes when features are correctly set as required by new revision 5 of the cluster
  • Enhancement: Event handling has received additional formality. The node now ensures that async handlers register as tasks with the node. Error logging contains more detail on the source of errors
  • Enhancement: $Changed events now run in a separate context from the emitter and errors will not interfere with the emitter
  • Fix: Switched "boot time" to be the time the node comes online instead of the time the OS started
  • Fix: Fixed patching of arrays to correctly allow to set arrays with fewer elements than the original array using set()

• @matter/nodejs

  • Breaking: The StorageBackendDisk class got removed including the "node-localstorage" dependency, but the name got reused and so the "StorageBackendDiskAsync" is now "StorageBackendDisk".
  • Enhancement: Added a UDP send guard to reject hanging send calls after maximum 1-2s
  • Fix: Improves async storage reliability and error handling to prevent empty storage files in crashing edge cases. With this change write actions need a bit longer but are more reliable, which mainly effects controller use cases when persisting the device attribute data on first subscribe
  • Fix: Also accept incoming UDP traffic from unknown network interfaces for Matter messages

• @matter/nodejs-ble

  • Enhancement: Upgraded Noble and Bleno and optimized stability with BLE device and controller operations

• @matter/nodejs-shell

  • Feature: Added parameters --qrCode and --qrCodeIndex to the commission pair command to also use QR Code strings for pairing
  • Fix: Prevents crash on startup when having set a Fabric label in config

• @matter/protocol

  • Breaking: updateReceived() callback on subscriptions is triggered after all updated data event are sent out.
  • Feature: Enhanced getMultipleAttributesAndEvents() to also return attributeStatus and eventStatus properties with errors returned from the read interaction
  • Feature: Added getMultipleAttributesAndStatus() and getMultipleEventsAndStatus() to InteractionClient to allow to also returned attribute and event errors from the read interaction
  • Enhancement: Allows to access attributes, events and commands in CLusterClient instances also by their ID.
  • Enhancement: Makes sure that the Node ID for commissioning of a new node is not already commissioned.
  • Enhancement: Returns the maximum interval in seconds when InteractionClient is used to establish a subscription
  • Fix: Makes sure to not Forward StatusResponseError cases that we generate locally to the device when not wanted
  • Fix: Enhances checks for Wi-Fi/Thread credentials in config for CommissioningFlow
  • Fix: Ensures that PASE establishments are guarded as defined by specification to prevent passcode brute force attacks
  • Fix: Informs the device when Controller cancels pairing because of a wrong passcode to allow direct retries

• @project-chip/matter.js

  • Breaking: Reduced exports to the relevant one for Controller usage. Please move for @matter/main for the rest.
  • Breaking: Remove the Legacy Device building API. Please use the new SeverNode based API which is more flexible and powerful.
  • Breaking: Changed signatures of commissionNode() and createInteractionClient() to provide options as object and not plain parameters
  • Breaking: The handling of the requestFromRemote parameter (first parameter) in get*Attribute methods in ClusterClients changed behavior! providing "false" will now never try to read from remote, "true" will always try to read from remote and "undefined" will use the default behavior (read from remote if not available locally or fabric scoped read). Only relevant if you used this parameter with value "false". Other use cases stay unchanged.
  • Feature: Allows to use a custom Root-NodeId, CertificateAuthority or CommissioningFlow implementation in the Controller
  • Feature: Allows to establish a secure PASE session to a device and use this to interact with the device in special pre-commissioning cases.
  • Enhancement: Exposing the current Subscription Interval on `PairedNode::currentSubscriptionIntervalSeconds()
  • Enhancement: Adjusted the initial Device connection to Read-All before subscribing to also have initial values for not-changed attributes
  • Enhancement: Added new PairedNode event connectionAlive to expose the subscription alive triggers (on changes or after max interval)
  • Fix: Fixes an edge case in reconnection handling

• @project-chip/* packages (beside above)

  • Breaking: Packages are removed! Please use the new packages under @matter/* if needed

About matter.js

matter.js is an open-source project developing a JavaScript SDK that implements the Matter IoT Standard, created by the Connectivity Standards Alliance and its members. It’s designed to simplify building Matter-compatible devices, bridges, and controllers. With its Node.js-based architecture, matter.js runs on any OS that supports Node.js.

The included shell application makes it easy to explore and interact with Matter devices during development and testing. While the project is still evolving toward full Matter specification coverage, matter.js already supports key functionalities — and the first device built with it has been officially certified, with more certifications on the way.
Tens of thousands of users are already using matter.js in various (uncertified) open-source Smart Home projects, proving interoperability with major ecosystems like Amazon, Apple, Aqara, Google, and SmartThings.