File List
Not logged in

Files of check-in [d26d71cd86] in directory wiki_references/2019/software/mail_and_messaging/matrix_org/src_from_GitHub/the_repository_clones/matrix-react-sdk   [history]


matrix-react-sdk

This is a react-based SDK for inserting a Matrix chat/voip client into a web page.

This package provides the React components needed to build a Matrix web client using React. It is not useable in isolation, and instead must be used from a 'skin'. A skin provides: * Customised implementations of presentation components. * Custom CSS * The containing application * Zero or more 'modules' containing non-UI functionality

As of Aug 2018, the only skin that exists is vector-im/element-web; it and matrix-org/matrix-react-sdk should effectively be considered as a single project (for instance, matrix-react-sdk bugs are currently filed against vector-im/element-web rather than this project).

Translation Status

Translation status

Developer Guide

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 native iOS (https://github.com/matrix-org/matrix-ios-kit) and Android (https://github.com/matrix-org/matrix-android-sdk) SDKs.

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

Please follow the standard Matrix contributor's guide: https://github.com/matrix-org/matrix-js-sdk/blob/develop/CONTRIBUTING.rst

Please follow the Matrix JS/React code style as per: https://github.com/matrix-org/matrix-react-sdk/blob/master/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 the maintenance burden of customising and overriding these components for Element can seriously impede development. So right now, there should be very 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 are 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 be aware of and uphold:

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:

git clone https://github.com/matrix-org/matrix-js-sdk
cd matrix-js-sdk
git checkout develop
yarn link
yarn install

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

git clone https://github.com/matrix-org/matrix-react-sdk
cd matrix-react-sdk
git checkout develop
yarn link matrix-js-sdk
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:

yarn test

End-to-End tests

Make sure you've got your Element development server running (by doing yarn start in element-web), and then in this project, run yarn run e2etests. See test/end-to-end-tests/README.md for more information.