SDKs · Node
Node — Runtime support
Declarative runtime support matrix for @mattermode/node. Verified runtimes run the full conformance corpus in CI; supported runtimes pass a smoke subset; experimental runtimes ship behind a feature flag.
Last updated
Runtime support matrix
Where @mattermode/node runs, and what conformance guarantees come with each runtime.
TL;DR. Node 20+, Node 22 (LTS), and Bun ≥ 1.1 are verified — the full SDK conformance corpus runs against each on every commit. Deno, Workers, and modern browsers are supported via the Web Crypto path. React Native is experimental and requires a SubtleCrypto polyfill.
Support tiers
Three tiers map directly onto the canonical contract published from @matter/sdk-conformance:
| Tier | What it means |
|---|---|
| verified | Full SDK conformance corpus runs in CI on every commit. Bugs treated as P0. |
| supported | A smoke subset of the corpus runs in CI. Bugs treated as P1. Users should pin a known-good version. |
| experimental | Best-effort. Signatures and behaviour may change between minor releases. No CI gate. |
The tier classification is data — sourced from RUNTIME_MATRICES.node in packages/sdk-conformance. When this table and the data drift, CI fails.
Matrix
| Runtime | Version | Tier | Notes |
|---|---|---|---|
| Node.js | 20.x | verified | Primary target. Full conformance corpus runs in CI. |
| Node.js | 22.x | verified | Active LTS. Full corpus runs in CI. |
| Bun | ≥ 1.1 | verified | Native fetch + Web Crypto. Full corpus runs in CI. |
| Deno | ≥ 1.40 | supported | Uses Web Crypto for HMAC. Smoke + signing tests in CI. |
| Cloudflare Workers | latest | supported | No Node-specific APIs. Workers-compat smoke test in CI. |
| Browser | modern (ES2022) | supported | Web Crypto required. Public-key-only token flows tested. |
| React Native | ≥ 0.74 | experimental | SubtleCrypto polyfill required; minimal smoke test only. |
What the SDK guarantees per tier
verified — Every behaviour described in error handling, pagination, and webhooks works the same way it does in the type definitions. Streaming, retries, and idempotency replay are exercised against a fixture API on each commit.
supported — Authentication, request/response, error classes, and pagination work. Streaming may degrade on platforms without a native EventSource. Retries function but the exact backoff curve may be implementation-defined.
experimental — The package installs and authenticates. Beyond that, expect rough edges. Open an issue if something breaks; we will not block a release on it.
CI matrix
The Node SDK's CI matrix runs the conformance corpus against the verified row set on every PR. The matrix is wired in .github/workflows/sdk-node.yml and pulls runtime versions directly from RUNTIME_MATRICES.node. Adding a runtime to the verified tier is a code change, not a doc change.
See also
- SDK conformance harness — the contracts every SDK satisfies
- Error handling — the cross-SDK error class hierarchy
- Webhooks — streaming + retry guarantees