Matrix JavaScript SDK: Client-Server Library for JS

What is the Matrix JavaScript SDK?

Matrix JavaScript SDK is the client-server SDK for the Matrix protocol, written in TypeScript and usable as both a Matrix Node.js SDK and a Matrix browser SDK depending on where you import it. It wraps the Matrix Client-Server API into an object model — Room, RoomMember, User — and emits events for syncing, typing, membership changes, and incoming messages, maintained by Element for its own web and desktop clients.

Who is this SDK for?

Matrix JavaScript SDK fits developers building a decentralized messaging or collaboration client on the Matrix protocol who don't want to hand-roll /sync polling, room state tracking, or the Rust-backed crypto stack themselves. As a Matrix client SDK it suits both browser apps, via Webpack or Vite, and Node.js backends or bots, per the README's supported-platforms list — Element itself builds its web and desktop clients on it. Skip it if you're not targeting Matrix, or need a client for a language other than JavaScript/TypeScript, since this library only covers the JS/TS side of the protocol.

Core Capabilities of the SDK

• ✓Wraps the full Matrix Client-Server API into an object model — Rooms, RoomState, RoomMembers, and Users — and emits events when any of them change, per the README.
• ✓Handles /sync polling, pagination, and room initial sync on accepting an invite, so you don't poll the HTTP API by hand.
• ✓Local echo shows your outgoing message in the timeline right away, tagged as still sending, until the server confirms it — so there's no visible gap between clicking send and the message actually landing.
• ✓Automatically retries sends on network errors and on rate-limiting errors, and marks messages that ultimately fail as not sent, per the README.
• ✓End-to-end encryption runs through initRustCrypto(), which loads the WebAssembly bindings of the Rust matrix-sdk-crypto library rather than a JS-only crypto implementation.
• ✓Covers the harder crypto workflows out of the box: secret storage bootstrap, cross-signing setup, key backup, and device verification, all exposed through the CryptoApi interface.
• ✓Ships separate entry points for crypto (matrix-js-sdk/lib/crypto-api), spec-level types (matrix-js-sdk/lib/types), and MSC4108 QR-code login and rendezvous (matrix-js-sdk/lib/rendezvous), so you import only what you need.
• ✓Handles authenticated media downloads and thumbnails via mxcUrlToHttp plus a bearer Authorization header, for servers implementing MSC3916 (Matrix 1.11).

Getting Started with Installation

Matrix JavaScript SDK installs with a single command: pnpm add matrix-js-sdk — the README suggests pnpm over npm, linking out to pnpm's own installation guide for anyone who doesn't have it set up yet. Once installed, import * as sdk from "matrix-js-sdk" and call sdk.createClient({ baseUrl: "https://matrix.org" }) to get a MatrixClient instance pointed at a homeserver. The minimum Matrix server version the SDK targets is v1.1, and the README flags upfront that some servers require an Authorization header for media downloads, so check the authenticated-media notes before going further. From there, client.startClient({ initialSyncLimit: 10 }) starts the sync loop that populates rooms and timelines.

Building with the SDK: Code Examples

Send a message with client.sendEvent(roomId, "m.room.message", { body: "message text", msgtype: "m.text" }, "", callback), then listen for it with client.on(RoomEvent.Timeline, (event, room, toStartOfTimeline) => { ... }), filtering on event.getType() === "m.room.message". For connection state, client.on(ClientEvent.sync, (state) => { ... }) reports when the client reaches the PREPARED state after its first sync, while RoomMemberEvent.Typing and RoomStateEvent.Members cover typing indicators and membership lists. The default store is an in-memory MemoryStore that holds events as they arrive, so client.store.rooms gives you the cached timeline per room without another round trip to the server. For encryption, await matrixClient.initRustCrypto() turns on the Rust-backed crypto stack before you call matrixClient.getCrypto() for cross-signing, secret storage, or key backup.

Exploring Other Matrix SDKs

Frequently Asked Questions

The problem it solves

Chat application development on Matrix's federated network means hand-rolling /sync polling for real-time communication, tracking room and member state across dozens of event types, retrying on rate limits, and now integrating a WebAssembly-backed crypto stack for end-to-end encryption — all before a single line of chat UI gets written. Matrix JavaScript SDK exists because Element needed exactly that stack for its own web and desktop clients and open-sourced the result instead of leaving every Matrix client author to rebuild sync, state tracking, and Rust-crypto bindings independently.

Best use cases

• •Building a web-based Matrix chat client with a bundler like Webpack or Vite, using the SDK's Room and RoomMember object model instead of parsing /sync responses by hand.
• •Writing a Node.js Matrix bot or bridge that listens on RoomEvent.Timeline for incoming messages and replies via sendEvent, with automatic retry on rate-limit errors.
• •Adding end-to-end encryption to a Matrix client via initRustCrypto(), including cross-signing device verification and key backup, without reimplementing the Rust crypto bindings yourself.
• •Migrating an existing client off the legacy crypto stack onto Rust crypto, tracked through the CryptoEvent.LegacyCryptoStoreMigrationProgress event.
• •Prototyping against a Matrix homeserver in Deno, though the README flags that path as unofficial.

Related repositories