Release matter.js 0.16 from 12.01.2026

[Apollon77]

matter.js 0.16 - Matter 1.4.2 Support, Scenes, OTA Updates, and New JavaScript Runtimes

We're excited to announce matter.js 0.16, bringing Matter 1.4.2 specification support, OTA software updates, and expanded runtime compatibility to the JavaScript Matter SDK.

What's New in Version 0.16

This release adds support for all new device types, clusters, and data types introduced in the Matter 1.4.2 specification, enabling the development of Matter-compatible devices, bridges, and controllers. The long-awaited Scenes Management feature, previously provisional, is now fully integrated and ready for ecosystem adoption.

A major addition in this release is full support for OTA Software Updates and BDX file transfers for matter.js controllers and devices. This feature required extended development time but delivers significant value. Updates can be queried from official Connectivity Standards Alliance sources via the Distributed Compliance Ledger, or provided directly for testing purposes. For controller developers, matter.js provides a convenient API to manage updates and consents for all connected nodes.

Last but not least, this version supports two new JavaScript runtimes, expanding matter.js use cases. You can now implement cross-platform desktop applications using the Electron framework and bring Matter into React Native-based mobile applications. Both additions demonstrate the flexibility of JavaScript as a platform for IoT development.

Beyond new features, this version includes numerous stability and reliability improvements to the Matter protocol stack.

Looking ahead, we'll focus on adding support for Matter 1.5.0, expanding support for remaining Matter protocol features, and finalizing the new Controller API. Stay tuned—more is on the way!

Breaking Changes

This version introduces several breaking changes that might affect your applications:

Matter Specification Changes

• On the matter protocol level the changes are primarily promoting existing features, clusters, and device types from provisional to officially supported status
• The Matter specification removed formerly existing fallback values for many fields. You may need to manually supply initial attribute values in places where defaults were previously provided.

Runtime Requirements

• matter.js now requires Node.js 20.19+, 22.13+, or 24.0+ (LTS versions). Node.js 18.x is no longer supported.

Epoch Time Handling

• All epoch values are now exposed based on January 1, 1970, as JavaScript typically handles dates, independent of the Matter epoch type. matter.js automatically converts all timestamps as needed in both directions. Background: Matter uses epochs based on 1.1.1970, but also epoch values based on 1.1.2000.

Storage Backend Changes

• Due to performance optimizations in the default storage manager (StorageBackendDisk), opening a storage with the same ID multiple times in parallel is no longer supported and will lead to unexpected results. Please ensure your code does not attempt this.
• Synchronous storage classes have been removed.

Controller API Preparations

• We're preparing the PairedNode-based Controller API for compatibility with the upcoming ClientNode-based Controller API. The storage structure for controllers has changed, and all data will be migrated automatically on first start. This can take some time.
• The structure remains backward compatible, allowing downgrades to earlier matter.js versions without data loss for now.
• Some PairedNode events and InteractionClient usage have changed to prepare for the upcoming API. These changes enable us to provide the same PairedNode-based API while using the new implementation under the hood, facilitating easy migration.
• We'll announce when the new API is ready for production use, though some components are already in use with this version.

Examples Package

• The @matter/examples package is no longer published to npmjs as our examples collection has grown significantly. Examples remain available in the main repository's examples directory and can be used to initialize new projects via npm init @matter.

Additional Changes

• Updates to our Time API, handling of central services, typing of Observables, and BLE instance registration also might require changes to your implementations. When using TypeScript the build should direct you to most of the places that require changes.

Please refer to the full Changelog below for complete details.

Get Involved

Update to matter.js 0.16 on npm, and share your feedback, experiences, and questions with us on GitHub or Discord—we're here to support you!

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

Changelog

• Breaking: matter.js now requires node.js 20.19+ or 22.13+ or 24.0+ (LTS versions). Node.js 18.x is no longer supported.

• Breaking: Because of the upgrade to TypeScript 5.9, all usages of Uint8Array were changed to use a more convenient own type alias Bytes

• Breaking: Matter 1.4.2 no longer specifies reasonable defaults for many fields, so you may find new places where you need to manually supply an attribute value

• Breaking: The default Node.js storage manager (StorageBackendDisk) was optimized for performance which requires not opening multiple storages for the same ID at the same time. So check your usage of StorageService, if you use it directly too.

• @matter/*:

  • Upgraded to Matter specification version 1.4.2

• @matter/examples

  • Breaking: This package is no longer published. The examples are moved in the repository into the examples/ directory. Simply use the project creator npm init @matter to create a new project based on one of the examples.

• @matter/general

  • Breaking: Our time API is upgraded, most notably with proper typing for time intervals. This makes time handling more consistent and safer, but it does change how you convey intervals to matter.js. For example: delay: Seconds(1) rather than delayMs: 1000.
  • Breaking: There are other small time changes such as converting nowMs() (a function) to nowMs (a property).
  • Breaking: SyncStorage interface got removed
  • Breaking: MaybeAsyncStorage got renamed to Storage because it is the only interface from now on
  • Breaking: Some central services, especially MdnsService, are now tracked automatically by usages and will close correctly when no longer needed. Closing MdnsService manually is not needed anymore.
  • Breaking: The types for observables with synchronous emitters no longer accept async observers. Most observables are async but if you encounter a type error you need to track your promise outside the observable
  • Feature: Adds Blob support to the Storage interface
  • Feature: Add BDX (Bulk Data eXchange) protocol support according to Matter specification
  • Feature: Added support for multiple hash algorithms (SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256, SHA3-256) via HashAlgorithm enum with IANA identifiers
  • Enhancement: Enhanced Crypto.computeHash() to support streaming data via ReadableStreamDefaultReader and AsyncIterator in addition to Bytes and Bytes[] for memory-efficient hash computation
  • Enhancement: Added platform abstractions for of HTTP, WebSockets, and MQTT
  • Enhancement: Added polyfills and additional types for decorators
  • Enhancement: Split out access to random values from the Crypto interface to an Entropy interface
  • Enhancement: Added support for shared Environment services by tracking usages and closing when the last user is gone
  • Enhancement: Specializes camelize() to stop processing when $ is reached to better handle special names for custom clusters
  • Enhancement: Convert PromiseQueue to Semaphore with the obtain / release approach
  • Enhancement: Update Session timing parameters during CASE/PASE as delivered by the peer already during session establishments
  • Fix: Ensures that StandaloneAck messages are always considering the corresponding Secure channel protocol ID

• @matter/model

  • Feature: You can now use Ecma TC39 stage 3 decorators to associate assign Matter semantics to JavaScript classes
  • Feature: You can now reference subproperties in constraints as required by Matter 1.4.2
  • Feature: Constraints now support Matter 1.4.2 functions minOf and maxOf
  • Enhancement: Model API is improved to simplify element filtering based on conformance

• @matter/node

  • Breaking: Endpoint and Node initialization values now require the correct type for some time values and IDs. So for example, VendorId(1234) instead of just 1234
  • Breaking: SubscriptionBehavior is renamed to SubscriptionsServer with corresponding ID change to "subscriptions". This means in part that matter.js will ignore saved subscriptions, but devices will recreate them automatically
  • Breaking: The agentFor method of ActionContext has moved to Endpoint. You likely do not use this directly but if you do you must change context.agentFor(endpoint) to endpoint.agentFor(context)
  • Breaking: We have refactored the ActionContext class to better delineate fields that apply to operations triggered locally vs those triggered by authenticated peers. ActionContext may be a RemoteActorContext or LocalActorContext. You can determine the actor type and access relevant fields using new type guards hasRemoteActor or hasLocalActor and new type assertion assertRemoteActor. These replace the former offline field of ActionContext
  • Breaking: The FabricAction enum emitted by CommissioningServer is replaced with a simple string type
  • Feature: matter.js now natively supports remote access to Matter nodes via non-Matter protocols. You can add HttpServer, WebSocketServer and/or MqttServer to your ServerNode to enable HTTP, WebSocket, and MQTT access respectively
  • Feature: You can now use Ecma TC39 stage 3 decorators to customize the schema associated with a Behavior implementation
  • Feature: New StateStream component offers a high-level API for monitoring changes across multiple nodes
  • Feature: Add default implementation for the Thermostat cluster according to Matter 1.4.2 specification. All features except MSCH and SB (which is considered provisional) are implemented. See the ThermostatServer class for details.
  • Feature: Added feature complete default implementation for the Scenes Management cluster according to Matter 1.4.2 specification.
  • Feature: Added the VendorIdVerification algorithm on device side according to Matter 1.4.2 specification. Controller side is only partially implemented yet.
  • Feature: Added default implementations for OtaSoftwareUpdateRequestor/Provider clusters according to Matter specification.
  • Feature: Added OTA management support component (SoftwareUpdateManager)
  • Enhancement: Adds "maybeReactTo" which only registers the listener when the event exists.
  • Enhancement: Enhances Endpoint#eventsOf and Endpoint#setStateOf with overrides so you can use the ID to obtain variants with generic typing
  • Enhancement: We now enforce bounds for integer types even if not specified explicitly by constraint
  • Enhancement: Also allow to use the Endpoint#set() method with attribute ids instead of attributeNames
  • Fix: Ensures that the InLevel does not interfere with *WithOnOff commands in the Level Control cluster
  • Fix: Ensures correct behavior for announcements and fabric table updates in case of updating fabrics

• @matter/nodejs

  • Breaking: The default storage manager (StorageBackendDisk) was optimized for performance which requires not opening multiple storages for the same ID at the same time. So check your usage of StorageService, if you use it directly too.
  • Enhancement: Uses "stat" to determine storage file existence instead of reading all content
  • Enhancement: Exposes Node's native HTTP server via new abstractions in @matter/general
  • Fix: Corrects network interface selection logic for windows

• @matter/nodejs-ble

  • Fix: Updating Noble and Bleno to enhance compatibility on macOS and Windows

• @matter/nodejs-shell

  • Feature: Added cert command for DCL certificate management with subcommands: list, details, as-pem, delete, and update
  • Feature: Added ota command for OTA update management with subcommands: info, extract, verify, list, add, delete, and copy for managing OTA image files in storage
  • Feature: Added new commands to the node commands to check, download and apply OTA updates for nodes

• @matter/protocol

  • Breaking: The platform-specific BLE abstraction has changed so that higher-level logic may be shared across platforms
  • Breaking: Low-level advertising APIs have changed significantly; in particular, MdnsBroadcaster, MdnsInstanceBroadcaster and MdnsScanner are replaced by MdnsServer, MdnsAdvertisement and MdnsClient
  • Breaking: The Ble.get() singleton is removed; components now instead retrieve the Ble service from the environment
  • Breaking: Moved some controller API classes (Attribute/Event/Command/InteractionClient) into @project-chip/matter.js/cluster package and adjusted to use Node Interactable as backing
  • Breaking: Reading multiple/all attributes via InteractionClient is always reading the data from the device and no longer enrich the result with already known data (option enrichCachedAttributeData is no longer supported). Ideally, use ClusterClient or new Node-based APIs to access the already stored data.
  • Feature: Adds support for advertising of TCP and ICD services (but matter.js does not yet implement those features otherwise)
  • Feature: Adds support for extended advertisement
  • Feature: Added support for Case Authenticated Tags (CATs) in operational CASE sessions for enhanced access control
  • Feature: Added support to read and parse ASN.1 formatted certificates
  • Feature: Added DclCertificateService for managing Product Attestation Authority (PAA) certificates from the Distributed Compliance Ledger (DCL) with automatic updates from production DCL, test DCL, and GitHub development repositories
  • Feature: Added DclOtaUpdateService for checking and downloading Over-The-Air (OTA) software updates from DCL with full validation and checksum verification
  • Feature: Added DclVendorInfoService for retrieving vendor information from DCL
  • Feature: Added OTA image processing utilities (OtaImageReader, OtaImageWriter) for reading, validating, extracting, and creating Matter OTA update files
  • Feature: (@ArtemisMucaj) Added support to pass / generate an intermediate CA in the CertificateAuthority class, when used the NOCs are signed with the ICAC cert
  • Enhancement: (@bhargavnagotha9) Allows the Root keypair to be optional when ICAC is provided
  • Enhancement: MDNS broadcasts more aggressively until a connection is established
  • Enhancement: MDNS and BLE advertising schedules are now configurable and conform to Matter and DNS-SD specifications
  • Enhancement: MDNS client and server efficiency is improved with a shared socket and message parser
  • Enhancement: MDNS Truncated Queries are now handled correctly
  • Enhancement: matter.js no longer uses SO_REUSEADDR on the Matter port, so you can no longer accidentally start two nodes at the same address simultaneously
  • Enhancement: Increases the limitation of parallel exchanges when sending messages to 30 (was 5 before)
  • Enhancement: Migrate Commissioning Flow to ClientInteraction as bases
  • Enhancement: FabricAuthority automatically rotates the operational Fabric NOC key pair on start once (for Controller cases)
  • Adjustment: Subscription data are no longer being flushed when a subscription is replaced by a new one with keepSubscriptions=false
  • Adjustment: When setting certificates and a ICAC is provided but equals the root CA, the ICAC is ignored (workaround of issues with one ecosystem)
  • Fix: Controller networking was previously throwing the incorrect error after a communication timeout
  • Fix: Ensures to only include the MaxTcpMessageSize in Session parameters when TCP is enabled
  • Fix: Fixes the used ACL level for wildcard writes
  • Fix: (@ArtemisMucaj) Fixes noc trust chain verification; verify against both RCAC and ICAC if present

• @matter/react-native

  • Fix: (@Luxni) Update UDP, BLE and Crypto usage to work with React Native

• @matter/types

  • Breaking: All "epoch-s" and "epoch-us" values are now converted automatically to the correct matter epoch, so that your own code can just use normal 1970-based epochS/US values. If you converted yourself to the Matter 2000-based values before, please remove this conversion.
  • Enhancement: The duplicate event priority definition EventPriority is deprecated; use the generated Priority enum instead
  • Fix: Ensures correct Number ranges for nullable and non-nullable numbers on TLV level

• @project-chip/matter.js

  • Breaking: PairedNode.state renamed to PairedNode.connectionState!
  • Breaking: PairedNode attribute change callbacks and events does not contain the changed and oldValue properties anymore
  • Breaking: Some PairedNode API methods got slightly reduced in functionality, but that should not affect most users
  • Breaking: The Storage location of the controller base data has moved. The data will be migrated automatically on the first start of the new version (be aware, this can take some seconds!)
    • Cached node attribute data (formerly node-<ID>.* in the main storage) are now located in nodes.peerX.endpoints.* because they are now managed
    • The fabric (formerly "credentials.fabric") is now located at "fabrics.*"
    • The certificates (formerly other credentials.*) are now located in certificates.*
    • The list of commissioned nodes (formerly "nodes.commissionedNodes") is now integrated in the node peer data (nodes.peerX)
  • Feature: Added new option enableOtaProvider to CommissioningControllerOptions to enable OTA Provider functionality
  • Enhancement: The PairedNode is data wise now backend by a ServerNode instance which acts as controller and provides all data management and peer access. This API can alredy be moved directly by using PairedNode.node - some convenience methods are also dorectly mapped on the PairedNode itself (see below). initial connection and reconnection management is still handled by PairedNode and will move later.
  • Enhancement: Added more convenient accessors for endpoint cached read-only state: Endpoint.state property for attributes for all clusters in generic way and Endpoint.stateOf() for typed access for a defined Client behavior
  • Enhancement: Added more convenient accessors for endpoint commands: Endpoint.commands property for commands for all clusters in generic way and Endpoint.commandsOf() for a types access for a defined Client behavior
  • Enhancement: Added PairedNode.parts and Endpoint.parts as Map property to access all endpoints of a node
  • Enhancement: Added PairedNode.state, PairedNode.stateOf(), PairedNode.commands and PairedNode.commandsOf() to access all endpoints of te root endpoint in a more convenient way

• @matter/mqtt

  • Feature: New package implementing @matter/main MQTT abstraction using MQTT.js

• @matter/nodejs-shell

  • Fix: Changed the shell CLI option to enable ble to "--ble-enable" to not conflict with internal variables
  • Adjustment: Adjusted to build ESM package by default

• @matter/nodejs-ws

  • Feature: New package implementing @matter/main WebSocket abstraction using ws package and Node.js HTTP server

• Example Applications

  • (markus-becker-tridonic-com) Added an Electron-based example application implementing a Matter controller with BLE commissioning support for Thread networks to demonstrate the use of Matter.js in a desktop environment

• Other

  • Feature: For developers working with the matter.js repository on Macs and Windows, we now offer a devcontainer to facilitate native Linux development

About matter.js

matter.js is an open-source JavaScript SDK that implements the Matter IoT standard, developed by the Connectivity Standards Alliance and its members. It simplifies the process of building Matter-compatible devices, bridges, and controllers.

Built on a Node.js-based architecture, matter.js runs on any operating system that supports Node.js and other compatible JavaScript frameworks like Bun, Electron, or React Native. The included shell application allows developers to easily explore and interact with Matter devices during development and testing.

While still evolving toward full specification coverage, matter.js already supports key functionality. Some devices built with it have been officially Matter-certified, with more certifications underway.

Tens of thousands of users are already using matter.js in open-source (though uncertified) smart home projects, demonstrating interoperability with major ecosystems such as Amazon, Apple, Aqara, Google, SmartThings, and Home Assistant.

matter.js is an open source project maintained by the Open Home Foundation.

[HuggeK]

Could we get this post linked in the Release, so if one subscribes to Releases they can get this link directly in their inbox? Unfortunately one can´t subscribe to a category tag in github discussions.