Release 0.17.0 on 20.05.2026

[Apollon77]

matter.js 0.17 — Matter 1.5.1, TCP Support, Controller Optimizations, and More

We're excited to announce matter.js 0.17, bringing Matter 1.5.1 specification support, TCP support, enhancements for Controller usage, and many other improvements to the JavaScript Matter SDK.
Thanks also go to all community contributors who keep making matter.js better with every release.

What's New in Version 0.17

This release adds support for all new device types, clusters, and data types introduced in the Matter 1.5.1 specification, enabling the development of Matter-compatible devices, bridges, and controllers.

Beyond this, the main focus of this version was completing and optimizing the Controller features of matter.js. To that end, we re-implemented large parts of the discovery, connection, and reconnection logic for devices, now also taking into account the differences between Ethernet, Wi-Fi, and Thread devices and the specific requirements of each transport. We verified this in the field with Thread networks containing more than 400 devices and confirmed smooth startup and operation.

The newly added TCP support can be enabled optionally and used preferentially for outgoing connections, with an automatic fallback to UDP depending on device support and needs.

Additionally, refactoring of several internal data structures reduces matter.js's RAM usage by 20–50% compared to the previous version. I want to especially thank @lauckhart for the effort he invested in these areas!

Controllers built with matter.js now also verify Device Attestation and Certification, including certificate revocation checks as defined by the Matter specification, and allow you to decide whether to continue commissioning a device based on the results.

For Devices and Bridges, we have added a specification-compliant implementation of the DoorLock cluster (excluding Aliro features), as well as support for client clusters and Bindings, with a convenient development API to implement the relevant logic once Bindings are established.

Furthermore, matter.js 0.17 introduces a new WAL-based storage engine (which will become the default in the future) and also allows you to choose SQLite as the storage engine — both including automatic migration depending on the configured engine.

Beyond these new features, this version includes numerous stability and reliability improvements to the Matter protocol stack and moves the new Controller/Client closer to finalization.

Looking ahead, we'll focus on expanding support for the remaining Matter protocol features and continue finalizing the new Controller API. Stay tuned — there's more to come!

Breaking Changes

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

Matter Specification Changes

• On the Matter protocol level, the changes primarily promote existing features, clusters, and device types from provisional to officially supported status
• The Matter specification removed several attributes and features that were flagged as "Zigbee only" and were therefore never relevant to Matter
• Some namespaces were renamed and now use a "Common*" prefix

Storage Backend

• Blob/File-related storage methods were removed from the standard Storage implementation and moved to a dedicated BlobStorage

Additional Changes

• More breaking changes affect the General, Model, and Protocol packages if you used these internal parts of the APIs
• For React Native, we updated the AsyncStorage package, which introduced a breaking change; a compatibility variant is also available to ease migration

Please refer to the full Changelog below for complete details.

Get Involved

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

Changelog

• Breaking: Matter 1.5/1.5.1 specification introduces some changes, as always with new Matter specification versions. You might need to adjust your code.

  • Some Namespaces were renamed and now have a "Common*" prefix
  • Several previous "Zigbee only" features, attributes and commands were removed because they were never allowed for Matter

• @matter/*

  • Upgraded to Matter specification version 1.5/1.5.1
  • 20%–50% RAM usage reductions and improvements

• @matter/general

  • Breaking: Blob/File-related storage methods were removed from the normal Storage implementation
  • Breaking: DnsCodec.decodeTxtRecord/encodeTxtRecord and the TxtRecord factory now operate on Bytes[] per RFC 6763 §6 so binary TXT values (e.g. Thread MeshCoP xa, xp, at, pt, sb, dd) survive encode/decode losslessly; encodeTxtRecord and TxtRecord accept (Bytes | string)[] so ASCII-only senders are unchanged
  • Feature: Added a new wal-based storage engine (not yet the default) to optimize persistence
  • Feature: DnssdName.parameters and IpService.parameters now return a DnssdParameters instance — a ReadonlyMap<string, string> plus a .raw(key): Bytes accessor for binary TXT consumers (e.g. Thread Border Router enrichment)
  • Enhancement: Added locking to storage implementations to prevent concurrent access issues and data corruption
  • Enhancement: Split out Blob-Storage into its own dir-based BlobStorage implementation
  • Enhancement: Added Storage Migration logic that can generically migrate between different storage engines
  • Enhancement: LogFormat.format renders any Diagnostic-loggable value to a string in the specified format (defaults to plain text)

• @matter/main

  • Feature: Added version string export that exposes the published matter.js version

• @matter/model

  • Breaking: Type-specific Model subfields such as "clusters" and "attributes" no longer support array-like positional access; use Matter.clusters.at(4) instead of Matter.clusters[4]
  • Breaking: Attributes declared by decorators (@attribute(...)) now default to read-only (R V); apply the writable decorator to attributes that must accept writes
  • Enhancement: Model preparations for Matter 1.5 and 1.5.1
  • Enhancement: The fluent API for manipulating the Matter data model is improved
  • Enhancement: Enhances decorator capabilities for attributes, clusters, and (matter and non-matter) commands

• @matter/node

  • Feature: (@adeepn) Added DclBehavior for centralized DCL configuration via environment variables (MATTER_DCL_*), config files, or programmatic setup
  • Feature: CommissioningClient.BaseCommissioningOptions now accepts wifiNetwork, threadNetwork, regulatoryLocation, and regulatoryCountryCode for passing network credentials and regulatory configuration during commissioning
  • Feature: onAttestationFailure commissioning option for controlling attestation validation policy (true/false/callback with typed findings)
  • Feature: ServerNode Network behavior options allow to set tcp (boolean) to enable TCP support for the server node
  • Feature: ServerNode Network behavior options allow to set transportPreference ("udp"/"tcp") to define the preferred connection type when peers support both. "udp" is the default and fallback
  • Feature: DoorLockServer is fully implemented except for Aliro features
  • Feature: The new Supervision() factory allows for fine-grained control of validation for state, commands, and arbitrary JS values
  • Feature: Added Endpoint.get() and Endpoint.getStateOf() — async read API with optional fabricFilter control; on a client endpoint issues a single batched Matter Read; on a server endpoint returns a snapshot of local state
  • Feature: Added Endpoint.featuresOf() / maybeFeaturesOf() — typed access to a cluster behavior's active feature flags
  • Feature: Added Endpoint.globalsOf() / maybeGlobalsOf() — exposes the global cluster attribute state
  • Feature: Allows ServerNode endpoints to declare client clusters via e.g. OnOffLightDevice.with(OccupancySensingClient). Mandatory clients are auto-registered
  • Feature: Added support for Cluster client bindings: BindingServer events established / removed are emitted for defined bindings with Node references preinstalled on the materialized endpoint. See the new OccupancyBindingDevice example. To receive attribute changes from a bound peer set resolution.node.set({ network: { defaultSubscription: Read(Read.Attribute({ ... })), autoSubscribe: true } })
  • Enhancement: Behavior events interactionEnd and interactionBegin now also fire for local act() writes, to be in sync with wire-driven interactions
  • Enhancement: Added string-id overloads to commandsOf(), eventsOf(), stateOf()/maybeStateOf()
  • Enhancement: Re-establish subscriptions in parallel per peer on device/bridge startup
  • Enhancement: Added more warnings on invalid values for BasicInformation cluster
  • Adjustment: Because we saw devices in the wild that needed up to 2 minutes to respond to mDNS queries, we increased the discovery time for commissioning targets to 3 minutes (previously 1 minute)
  • Fix: Ensures that attribute changes which happened during an initial subscription seeding with dataVersion filtering are still reported afterwards
  • Fix: Only exports atomic-commands in Thermostat cluster server when relevant features are supported
  • Fix: Properly cancels subscriptions that were canceled by the peer but were still in resubmission state
  • Fix: Preserves clusters in the structure even if they are not specified in the serverList of the endpoint but are reported in data ("Schrödinger's cluster")
  • Fix: You can now assign bare objects composed of managed values to state properties
  • Fix: ClientNode setStateOf accepts FabricIndex.OMIT_FABRIC for fabric-scoped struct entries (Matter §7.13.6) and substitutes the peer's assigned fabric index so the local cache mirrors what the peer stores

• @matter/nodejs-ble

  • Fix: Fixes several crash or blocking cases around BLE and the usage in commissioning

• @matter/nodejs-shell

  • Feature: Added cert check-revoked command for checking certificate revocation data
  • Enhancement: Allows configuring whether test OTA images are also accepted when devices query for updates

• @matter/protocol

  • Breaking: Removed automatic retry-logic for interactions on node-reachability issues; a new session will be initialized automatically afterward
  • Breaking: Some of the lower-level APIs in @matter/protocol have changed. This will be transparent to most users
  • Feature: We have rewritten the logic for establishing operational connections to other nodes. The new implementation should be faster, more resilient, and offers more knobs for tuning
  • Feature: A new "network profile" feature allows you to tune parallelism and other interaction parameters based on categories including transport type and thread channel
  • Feature: matter.js now responds immediately to IP changes advertised via MDNS
  • Feature: (@adeepn) DclConfig is now an interface with namespace defaults instead of a singleton; DclClient accepts DclConfig for configurable endpoints
  • Feature: (@adeepn) DclCertificateService and DclOtaUpdateService accept custom DCL endpoint configuration via options
  • Feature: Device attestation validation during commissioning per Matter spec 6.2.3.1 — certificate chain verification, attestation signature/nonce, Certification Declaration validation, and certificate revocation checks via CRL
  • Feature: Attestation findings model with error/warning/info levels and configurable policy callback for custom commissioning decisions
  • Feature: CRL revocation support in DclCertificateService — fetches from production DCL on demand, validates the signer chain against trusted PAAs, verifies CRL signature and integrity
  • Feature: CertificationDeclaration.parse() for CMS/PKCS#7 signed CD extraction and signature verification
  • Feature: Enhances DclVendorInfoService and DclCertificateService with an option to seed data to support cases where no internal connection is available (@matter/dcl-data package gets published daily)
  • Enhancement: Attestation local checks (nonce, signature, VendorID, CD fields) run even without DclCertificateService; DCL-dependent checks (PAA trust, chain, revocation) require it
  • Enhancement: Server-side DeviceCertification validates DAC/PAI VendorID and ProductID against product description at startup
  • Enhancement: Enhances the strategy when multiple devices are discovered for the same commissioning target
  • Enhancement: When multiple IP addresses are available for a device during commissioning, all are tried in parallel for faster connection
  • Enhancement: An AbortSignal can now be passed to cancel an in-progress commissioning attempt; the PASE layer sends InvalidParameter to avoid a 60-second device lockout
  • Enhancement: Several enhancements around session management when nodes reconnect or new sessions get pushed by the device
  • Enhancement: Several enhancements around OTA updates and transfers, also when nodes restart in the middle of the process
  • Enhancement: Add Product-Info API to VendorInfoService to expose DCL information for a given VendorId and ProductId
  • Enhancement: Probes discovered addresses and potentially updates session addresses when they change even when we have a valid working session
  • Enhancement: Optimizes operational connection logic during commissioning when multiple IPs are discovered
  • Enhancement: Uses a minimum of 60 seconds for thread/wifi network scan or connect timeouts even if devices announce lower values
  • Enhancement: WiFi/Thread network scan failures are no longer fatal during commissioning; scan failures are logged as warnings
  • Enhancement: Buffers storage of client state changes for up to 20 minutes to reduce I/O pressure
  • Adjustment: No longer ignores overly long incoming Matter messages, but still logs a warning
  • Adjustment: Tolerate operational certificates with 21-octet serial numbers (spec limit is 20, but seen in the wild with some LG TVs) and log a warning; longer serial numbers are still rejected
  • Adjustment: Refactor MdnsClient to also use the new DNS-SD-names logic
  • Fix: Ensure the incoming order of attribute changes is preserved when processing them even though no one should rely on any order
  • Fix: Better handle errors when the BLE connection is disconnected during a write action
  • Fix: Ensures that multiple discovered devices are tried when PASE establishment to the first device fails (e.g., because of a wrong passcode)
  • Fix: Do not announce devices as commissionable before the factory reset when the last fabric is removed
  • Fix: Fixes expiry logic where cached records for Commissionable devices could potentially never expire
  • Fix: For BDX cases also give the device the defined timeout of 5 minutes to ack/request the next packet
  • Fix: Accept SecureChannel StatusReport messages on any protocol exchange (e.g. BDX)
  • Fix: Ensures the Matter port on IPv4 is the same as on IPv6

• @matter/react-native

  • Breaking: We updated to @react-native-async-storage/async-storage v3. A v2-compatible class is available. See the package readme.

• @matter/tools

  • Breaking: This package is no longer published and replaced in internal usage

• @matter/types

  • Breaking: We have removed the deprecated device type definitions in DeviceTypes that have not received updates since Matter 1.1
  • Breaking: A number of semi-internal implementation details of cluster metadata have changed. The general API shape remains the same but some advanced use cases may require updates
  • Breaking: Removed some special pre-bound TLV string/byte-string schema exports, including TlvHardwareAddress
  • Feature: We've rewritten the typing system for clusters to simplify types, consume less runtime memory and work better with IDEs
  • Enhancement: Increases Matter TlvString/TlvByteString default maximum length to 65536 to cover WebRTC cases
  • Fix: NodeId.fromGroupId now produces a full 16-hex Group Node ID per Matter spec
  • Fix: (@snabb) TlvTaggedList now ensures schema/tag ordering when encoding (Matter Core §10.6.1). Added TlvTaggedListPreservingOrder for cases where ordering needs to be data driven (e.g. signed certificate sub-lists).

• @project-chip/matter.js

  • Feature: CommissioningController allows to set tcp (boolean) to enable TCP support for the controller
  • Feature: CommissioningController allows to set transportPreference ("udp"/"tcp") to define the preferred connection type when devices support both. "udp" is the default and fallback
  • Feature: CommissioningOptions when commission a new device allows to set an onAttestationFailure callback that gets called with attestation validation options and allows decisions to continue or block the commissioning. Default accepts but logs all failures.
  • Enhancement: CommissioningController.commissionNode() now uses the parallel PASE commissioning path for pre-discovered devices; WiFi/Thread/regulatory credentials and abort signal are fully propagated
  • Enhancement: Legacy Endpoint and PairedNode wrappers expose featuresOf() / maybeFeaturesOf() and globalsOf() / maybeGlobalsOf() matching the modern client endpoint
  • Enhancement: Legacy Endpoint and PairedNode wrappers now also expose get(), getStateOf(), eventsOf(), maybeStateOf() and string-id overloads on existing accessors for parity with the modern client endpoint
  • Adjustment: The "Waiting for device discovery" node state is now bound to the availability of IP announcements from MDNS
  • Fix: Fixes inverted autoConnect logic in CommissioningController

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 works with other compatible JavaScript runtimes such as Bun, Electron, and 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 running 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 and serves as the basis for the new Open Home Foundation Matter Server, currently in beta testing.

[washley]

Is there any rough estimate on when Home Assistant's matter app will be officially moved to this (without using the beta option)?

[Apollon77]

The current Beta version of the OHF Matter Server 0.7.0 we released beginning this week is basically the version that is planned to replace the Python server. We currently try to gather feedback to verify that this is all good and if all stays stable then we target "beginning of June" for the final step to replace the Python Matter Server by the new one.

I can only invite anyone to try the beta and support us in the verification