The Matrix JavaScript SDK (`matrix-js-sdk`) is the official client-server SDK for interacting with the Matrix open standard for secure, decentralized communication. It provides a comprehensive API for building Matrix clients, bots, and integrations, supporting both browser and Node.js environments. The current stable version is 41.3.0, with frequent release candidates like 41.4.0-rc.0 incorporating the latest Matrix specification updates and features. The project is actively maintained and sponsored by Element, who leverage it in their flagship web and desktop clients. Key differentiators include its robust end-to-end encryption support, comprehensive implementation of the Matrix client-server API, and its role as the foundational library for numerous Matrix ecosystem projects.
npm install matrix-js-sdkVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize the Matrix client, start syncing, listen for global sync state changes, fetch public rooms, and process incoming messages. It also includes comments for setting up E2E and sending messages.
Consult the official Matrix Specification v1.13 release notes and the `matrix-js-sdk` changelog for detailed migration paths. Update client code to align with any changed API behaviors or data formats.
Regularly monitor the Matrix specification development and keep `matrix-js-sdk` updated to avoid relying on features that may be deprecated or removed. Plan for periodic updates and compatibility checks.
Refer to the 'Authenticated Media' section in the `matrix-js-sdk` documentation to properly enable support for authenticated media, which usually involves providing appropriate credentials or configuring the client's HTTP handlers.
Ensure a `cryptoStore` (e.g., `MemoryCryptoStore` for testing, persistent storage for production) is passed to `createClient`. Follow the E2E setup guide in the SDK's documentation for full details on device management, key backups, and verification processes.
Upgrade your Node.js environment to version 22.0.0 or newer. Consider using a Node.js version manager like `nvm` to easily switch between versions.
Ensure `import { createClient } from 'matrix-js-sdk';` or `import * as sdk from 'matrix-js-sdk';` is used and `sdk.createClient({...})` is called with valid configuration parameters.Ensure your Node.js environment is configured correctly. If you're encountering this, you might be using an outdated version of `matrix-js-sdk` in Node.js, or trying to use a browser-specific build. Check the SDK's documentation for Node.js setup specifics, which might involve configuring a Node.js-specific HTTP client.
Check your `baseUrl` for correctness. Verify network connectivity to the Matrix home server. If using authentication, ensure user ID and access token are valid. Inspect the `res` object passed to the `ClientEvent.sync` listener for more specific error details from the server.
Ensure `cryptoStore` is provided during `createClient` initialization. Verify all participating devices in the room are cross-signed and trusted. If a device is new, it might need to wait for key sharing or be verified. Check key backups if applicable.
No dependency data recorded yet.