项目作者: matrix-org

项目描述 :
Matrix SDK for React Javascript
高级语言: TypeScript
项目地址: git://github.com/matrix-org/matrix-react-sdk.git
创建时间: 2015-06-09T16:37:07Z
项目社区:https://github.com/matrix-org/matrix-react-sdk

开源协议:Apache License 2.0

下载


npm
Tests
Playwright
Static Analysis
Localazy
Quality Gate Status
Coverage
Vulnerabilities
Bugs

matrix-react-sdk

matrix-react-sdk is now actively maintained at element-hq/matrix-react-sdk

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 and matrix-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 at element-hq/matrix-react-sdk.

See the following blog posts for more information:

Developer Guide

Platform Targets:

All code lands on the develop branch - master is only used for stable releases.
Please file PRs against develop!!

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:

React components in matrix-react-sdk come in two different flavours:
‘structures’ and ‘views’. Structures are stateful components which handle the
more complicated business logic of the app, delegating their actual presentation
rendering to stateless ‘view’ components. For instance, the RoomView component
that orchestrates the act of visualising the contents of a given Matrix chat
room tracks lots of state for its child components which it passes into them for
visual rendering via props.

Good separation between the components is maintained by adopting various best
practices 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 the
    component 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 in
    https://github.com/matrix-org/matrix-react-sdk/tree/master/res/css.

  • Per-view CSS is optional - it could choose to inherit all its styling from
    the 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/themes
    structural components (lacking presentation logic) and the simplest view
    components.

  • The view MUST only 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 to
    avoid CSS collisions. The base skin shipped by Matrix.org with the
    matrix-react-sdk uses the naming prefix “mx“. A company called Yoyodyne
    Inc 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 named
    by 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 div
    within the MessageTile view.

  • We deliberately use vanilla CSS 3.0 to avoid adding any more magic
    dependencies into the mix than we already have. App developers are welcome
    to use whatever floats their boat however. In future we’ll start using
    css-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 override
    styles 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 its
    own CSS. Instead, say .mx_RoomList .mx_RoomTile {} to scope the override
    only to the context of RoomList views. N.B. overrides should be relatively
    rare as in general CSS inheritance should be enough.

  • Components should render only within the bounding box of their outermost DOM
    element. Page-absolute positioning and negative CSS margins and similar are
    generally not cool and stop the component from being reused easily in
    different places.

Originally matrix-react-sdk followed the Atomic design pattern as per
http://patternlab.io to try to encourage a modular architecture. However, we
found that the grouping of components into atoms/molecules/organisms
made them harder to find relative to a functional split, and didn’t emphasise
the distinction between ‘structural’ and ‘view’ components, so we backed away
from it.

Github Issues

All issues should be filed under https://github.com/vector-im/element-web/issues
for now.

Development

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

Using yarn instead of npm is recommended. Please see the Yarn 1 install
guide
if you do not have it
already. This project has not yet been migrated to Yarn 2, so please ensure
yarn --version shows a version from the 1.x series.

matrix-react-sdk depends on
matrix-js-sdk. To make use of
changes in the latter and to ensure tests run against the develop branch of
matrix-js-sdk, you should set up matrix-js-sdk:

  1. git clone https://github.com/matrix-org/matrix-js-sdk
  2. cd matrix-js-sdk
  3. git checkout develop
  4. yarn link
  5. yarn install

Then check out matrix-react-sdk and pull in dependencies:

  1. git clone https://github.com/matrix-org/matrix-react-sdk
  2. cd matrix-react-sdk
  3. git checkout develop
  4. yarn link matrix-js-sdk
  5. yarn install

See the help for yarn link for
more details about this.

Running tests

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

  1. yarn test

Running lint

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

  1. yarn lint

Dependency problems

If you see errors (particularly “Cannot find module”) running the lint or test
commands, and yarn install doesn’t fix them, it may be because
yarn is not fetching git dependencies eagerly enough.

Try running this:

  1. yarn cache clean && yarn install --force

Now the yarn commands should work as normal.

End-to-End tests

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