1This directory contains the Matrix Client-Server SDK for Javascript available 2at https://github.com/matrix-org/matrix-js-sdk/. Current version is v11.1.0. 3 4The following npm dependencies are included: 5 6* @matrix-org/olm: https://gitlab.matrix.org/matrix-org/olm/-/packages/10 v3.2.8 7* another-json: https://www.npmjs.com/package/another-json/ v0.2.0 8* base-x: https://www.npmjs.com/package/base-x v3.0.8 9* bs58: https://www.npmjs.com/package/bs58 v4.0.1 10* browser-request: https://www.npmjs.com/package/browser-request v0.3.3 11* content-type: https://www.npmjs.com/package/content-type v1.0.4 12* events: https://www.npmjs.com/package/events v3.2.0 13* qs: https://www.npmjs.com/package/qs v6.9.6 14* unhomoglyph: https://www.npmjs.com/package/unhomoglyph 1.0.6 15 16The following npm dependencies are shimmed: 17 18* loglevel: The chat framework's logging methods are used internally. 19* safe-buffer: Buffer implementation used by base-x. 20* url: The global URL object is used directly. 21 22There is not any automated way to update the libraries. 23 24Files have been obtained by downloading the matrix-js-sdk git repository, 25using yarn to obtain the dependencies), and then compiling the SDK using Babel. 26 27To make the whole thing work, some file paths and global variables are defined 28in chat/protocols/matrix/matrix-sdk.jsm. 29 30## Updating matrix-js-sdk 31 321. Download the matrix-js-sdk repository from https://github.com/matrix-org/matrix-js-sdk/. 332. Modify `.babelrc` (see below). 343. Run yarn install 354. Run Babel in the matrix-js-sdk checkout: 36 `./node_modules/.bin/babel --source-maps false -d lib --extensions ".ts,.js" src` 37 (at time of writing identical to `yarn build:compile`) 385. The following commands assume you're in mozilla-central/comm and that the 39 matrix-js-sdk is checked out next to mozilla-central. 406. Remove the old SDK files `hg rm chat/protocols/matrix/lib/matrix-sdk` 417. Undo the removal of the license: `hg revert chat/protocols/matrix/lib/matrix-sdk/LICENSE` 428. Copy the Babel-ified JavaScript files from the matrix-js-sdk to vendored 43 location: `cp -r ../../matrix-js-sdk/lib/ chat/protocols/matrix/lib/matrix-sdk` 449. Add the files back to Mercurial: `hg add chat/protocols/matrix/lib/matrix-sdk` 4510. Modify `moz.build` to add/remove/rename modified files. 4611. Modify `matrix-sdk.jsm` to add/remove/rename modified files. 47 48### Custom `.babelrc` 49 50By default the matrix-js-sdk targets a version of ECMAScript that is far below 51what Gecko supports, this causes lots of additional processing to occur (e.g. 52converting async functions, etc.) To disable this, a custom `.babelrc` file is 53used: 54 55```javascript 56{ 57 "sourceMaps": false, 58 "presets": [ 59 ["@babel/preset-env", { 60 "targets": "last 1 firefox versions", 61 "modules": "commonjs" 62 }], 63 "@babel/preset-typescript" 64 ], 65 "plugins": [ 66 "@babel/plugin-proposal-class-properties" 67 ] 68} 69``` 70 71Babel doesn't natively understand class properties yet, even though we would 72support them, thus the class properties plugin. `last 1 firefox versions` tells 73babel to compile the code so the latest released Firefox (by the time of the 74last update of the packages) could run it. Alternatively a more careful 75`firefox ESR` instead of the full string would compile the code so it could run 76on any currently supported ESR (I guess useful if you want to uplift the code). 77 78## Updating dependencies 79 80First, follow the steps above. Then, check the `node_modules` directory that 81gets created by yarn. The necessary dependencies are available here, 82unfortunately each one has slightly different conventions. 83 84### Updating single file dependencies 85 86another-json, base-x, bs58 and content-type all have a single file 87named for the package or named index.js. This should get copied to the proper 88sub-directory. 89 90### Updating browser-request 91 92Follow the directions for updating single file dependencies, then modify the 93index.js file so that the `is_crossDomain` always returns `false`. 94 95### Updating events 96 97The events package is included as a shim for the native node `events` module. 98As such, it is not a direct dependency of the `matrix-js-sdk`. 99 100### Updating qs 101 102The qs package comes with two valid entry points, `dist/qs.js` and 103`lib/index.js`. The `dist` one is already prepared for use in browsers 104but still supports being loaded as commonJS module and it is only a single 105file, so we prefer that one. 106 107### Updating unhomoglyph 108 109This is simlar to the single file dependencies, but also has a JSON data file. 110Both of these files should be copied to the unhomoglyph directory. 111 112### Updating loglevel, safe-buffer, url 113 114These packages have an alternate implementation in the `../shims` directory and 115thus are not included here. 116 117### Updating olm 118 119The package is published on the Matrix gitlab. To update the library, download 120the latest `.tgz` bundle and replace the files in the `@matrix-org/olm` folder. 121