Repository files navigation

This is a react-based SDK for inserting a Matrix chat/voip client into a web page developed from 2015 through 2024 as part of the Matrix.org Foundation.

This package provides the React components needed to build a Matrix web client using React. It is not usable in isolation, and instead must be used from a 'skin'.

The only skin that existed during its development was vector-im/element-web; it andmatrix-org/matrix-react-sdk have effectively been considered as a single project (for instance, matrix-react-sdk bugs have been filed against vector-im/element-web rather than this project). For this reason it is now maintained atelement-hq/matrix-react-sdk.

See the following blog posts for more information:

• https://matrix.org/blog/2024/08/heart-of-matrix/
• https://element.io/blog/sustainable-licensing-at-element-with-agpl/

Platform Targets:

• Chrome, Firefox and Safari.
• WebRTC features (VoIP and Video calling) are only available in Chrome & Firefox.
• Mobile Web is not currently a target platform - instead please use the nativeiOS (https://github.com/matrix-org/matrix-ios-kit) and Android(https://github.com/matrix-org/matrix-android-sdk2) SDKs.

All code lands on thedevelop branch -master is only used for stable releases.Please file PRs againstdevelop!!

We use the same contribution guide as Element. Check it out here:https://github.com/vector-im/element-web/blob/develop/CONTRIBUTING.md

Our code style is also the same as Element's:https://github.com/vector-im/element-web/blob/develop/code_style.md

Code should be committed as follows:

• All new components:https://github.com/matrix-org/matrix-react-sdk/tree/master/src/components
• Element-specific components:https://github.com/vector-im/element-web/tree/master/src/components
  • In practice,matrix-react-sdk is still evolving so fast that themaintenance burden of customising and overriding these components forElement can seriously impede development. So right now, there should bevery few (if any) customisations for Element.
• CSS:https://github.com/matrix-org/matrix-react-sdk/tree/master/res/css
• Theme specific CSS & resources:https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes

React components in matrix-react-sdk come in two different flavours:'structures' and 'views'. Structures are stateful components which handle themore complicated business logic of the app, delegating their actual presentationrendering to stateless 'view' components. For instance, the RoomView componentthat orchestrates the act of visualising the contents of a given Matrix chatroom tracks lots of state for its child components which it passes into them forvisual rendering via props.

Good separation between the components is maintained by adopting various bestpractices that anyone working with the SDK needs to be aware of and uphold:

• Components are named with upper camel case (e.g. views/rooms/EventTile.js)

• They are organised in a typically two-level hierarchy - first whether thecomponent is a view or a structure, and then a broad functional grouping(e.g. 'rooms' here)

• The view's CSS file MUST have the same name (e.g. view/rooms/MessageTile.css).CSS for matrix-react-sdk currently resides inhttps://github.com/matrix-org/matrix-react-sdk/tree/master/res/css.

• Per-view CSS is optional - it could choose to inherit all its styling fromthe context of the rest of the app, although this is unusual for any but

• Theme specific CSS & resources:https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themesstructural components (lacking presentation logic) and the simplest viewcomponents.

• The view MUSTonly refer to the CSS rules defined in its own CSS file.'Stealing' styling information from other components (including parents)is not cool, as it breaks the independence of the components.

• CSS classes are named with an app-specific name-spacing prefix to try toavoid CSS collisions. The base skin shipped by Matrix.org with thematrix-react-sdk uses the naming prefix "mx*". A company called YoyodyneInc might use a prefix like "yy*" for its app-specific classes.

• CSS classes use upper camel case when they describe React components - e.g..mx_MessageTile is the selector for the CSS applied to a MessageTile view.

• CSS classes for DOM elements within a view which aren't components are namedby appending a lower camel case identifier to the view's class name - e.g..mx_MessageTile_randomDiv is how you'd name the class of an arbitrary divwithin the MessageTile view.

• We deliberately use vanilla CSS 3.0 to avoid adding any more magicdependencies into the mix than we already have. App developers are welcometo use whatever floats their boat however. In future we'll start usingcss-next to pull in features like CSS variable support.

• The CSS for a component can override the rules for child components.For instance, .mxRoomList .mx_RoomTile {} would be the selector to overridestyles of RoomTiles when viewed in the context of a RoomList view.Overrides _must be scoped to the View's CSS class - i.e. don't just define.mx_RoomTile {} in RoomList.css - only RoomTile.css is allowed to define itsown CSS. Instead, say .mx_RoomList .mx_RoomTile {} to scope the overrideonly to the context of RoomList views. N.B. overrides should be relativelyrare as in general CSS inheritance should be enough.

• Components should render only within the bounding box of their outermost DOMelement. Page-absolute positioning and negative CSS margins and similar aregenerally not cool and stop the component from being reused easily indifferent places.

Originallymatrix-react-sdk followed the Atomic design pattern as perhttp://patternlab.io to try to encourage a modular architecture. However, wefound that the grouping of components into atoms/molecules/organismsmade them harder to find relative to a functional split, and didn't emphasisethe distinction between 'structural' and 'view' components, so we backed awayfrom it.

All issues should be filed underhttps://github.com/vector-im/element-web/issuesfor now.

Ensure you have the latest LTS version of Node.js installed.

Usingyarn instead ofnpm is recommended. Please see the Yarn 1installguide if you do not have italready. This project has not yet been migrated to Yarn 2, so please ensureyarn --version shows a version from the 1.x series.

matrix-react-sdk depends onmatrix-js-sdk. To make use ofchanges in the latter and to ensure tests run against the develop branch ofmatrix-js-sdk, you should set upmatrix-js-sdk:

git clone https://github.com/matrix-org/matrix-js-sdkcd matrix-js-sdkgit checkout developyarn linkyarn install

Then check outmatrix-react-sdk and pull in dependencies:

git clone https://github.com/matrix-org/matrix-react-sdkcd matrix-react-sdkgit checkout developyarn link matrix-js-sdkyarn install

See thehelp foryarn link formore details about this.

Ensure you've followed the above development instructions and then:

yarntest

To check your code complies with the project style, ensure you've followed theabove development instructions and then:

yarn lint

If you see errors (particularly "Cannot find module") running the lint or testcommands, andyarn install doesn't fix them, it may be becauseyarn is not fetching git dependencies eagerly enough.

Try running this:

yarn cache clean&& yarn install --force

Now the yarn commands should work as normal.

We use Playwright and Element Web for end-to-end tests. Seedocs/playwright.md for more information.