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