Thore Cimbal
88c4e155ce
The repo had no upstream ancestry: a whole tree arrived in one commit in May, so
every update meant re-applying our patches by hand onto a fresh checkout, and a file
Element moved would take our lines with it silently.
The real base was found by measuring tree distance across develop rather than trusting
the changelog: deadd548, not the v1.12.17 tag. With that set as a temporary graft, this
merge computed as a proper three-way merge - 32 conflicts instead of 1757.
Resolutions, each decided rather than defaulted:
- 24 GitHub workflows stay deleted; we build on GitLab CI.
- MImageBody.tsx is gone upstream, migrated to MVVM. Our ClamAV error label moved into
ImageBodyViewModel.computeErrorLabel, ahead of the DecryptError branch, matching what
VideoBodyViewModel and FileBodyViewModel already do.
- Upstream extracted the room list item body into RoomListItemContent. Our call
participants list and its getInitials helper moved there; both sides' CSS classes and
both sides' props are kept.
- matrix-js-sdk follows upstream at 42.2.0 - our git ref pin was a workaround for a
stale ref, and following upstream is the point of this merge.
- Element Call stays ours. Checked before deciding: @element-hq/element-call-embedded
is referenced nowhere in the tree, while webpack.config.ts needs
@sorb/threadnet-call-embedded, so taking upstream's line would have deleted the noise
suppression from #0054 without a word.
The lockfile was regenerated with pnpm 11.20.0, which upstream now requires through
devEngines. CI already runs corepack enable, and onFail: download makes it fetch that
version by itself.
Not yet accepted: this needs a build and the ClamAV functional test - send an encrypted
file, receive a rejected one - before it goes near main.
Important Security Notes
Separate domains
We do not recommend running Element from the same domain name as your Matrix homeserver. The reason is the risk of XSS (cross-site-scripting) vulnerabilities that could occur if someone caused Element to load and render malicious user generated content from a Matrix API which then had trusted access to Element (or other apps) due to sharing the same domain.
We have put some coarse mitigations into place to try to protect against this situation, but it's still not good practice to do it in the first place. See https://github.com/element-hq/element-web/issues/1977 for more details.
Configuration best practices
Unless you have special requirements, you will want to add the following to your web server configuration when hosting Element Web:
- The
X-Frame-Options: SAMEORIGINheader, to prevent Element Web from being framed and protect from clickjacking. - The
frame-ancestors 'self'directive to yourContent-Security-Policyheader, as the modern replacement forX-Frame-Options(though both should be included since not all browsers support it yet, see this). - The
X-Content-Type-Options: nosniffheader, to disable MIME sniffing. - The
X-XSS-Protection: 1; mode=block;header, for basic XSS protection in legacy browsers.
If you are using nginx, this would look something like the following:
add_header X-Frame-Options SAMEORIGIN;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Content-Security-Policy "frame-ancestors 'self'";
For Apache, the configuration looks like:
Header set X-Frame-Options SAMEORIGIN
Header set X-Content-Type-Options nosniff
Header set X-XSS-Protection "1; mode=block"
Header set Content-Security-Policy "frame-ancestors 'self'"
Note: In case you are already setting a Content-Security-Policy header
elsewhere, you should modify it to include the frame-ancestors directive
instead of adding that last line.
Building From Source
Element is a modular webapp built with modern ES6 and uses a Node.js build system. Ensure you have the latest LTS version of Node.js installed.
Using pnpm instead of npm is recommended. Please see the pnpm install
guide if you do not have it already.
- Install or update
node.jsso that yournodeis at least the current recommended LTS. - Install
pnpmif not present already. - Clone the repo:
git clone https://github.com/element-hq/element-web.git. - Switch to the element-web directory:
cd element-web/apps/web. - Install the prerequisites:
pnpm install.- If you're using the
developbranch, then it is recommended to set up a proper development environment (see Setting up a dev environment below). Alternatively, you can use https://develop.element.io - the continuous integration release of the develop branch.
- If you're using the
- Configure the app by copying
config.sample.jsontoconfig.jsonand modifying it. See the configuration docs for details. pnpm distto build a tarball to deploy. Untaring this file will give a version-specific directory containing all the files that need to go on your web server.
Note that pnpm dist is not supported on Windows, so Windows users can run pnpm build,
which will build all the necessary files into the webapp directory. The version of Element
will not appear in Settings without using the dist script. You can then mount the
webapp directory on your web server to actually serve up the app, which is
entirely static content.
config.json
Element supports a variety of settings to configure default servers, behaviour, themes, etc. See the configuration docs for more details.
Labs Features
Some features of Element may be enabled by flags in the Labs section of the settings.
Some of these features are described in labs.md.
Caching requirements
Element requires the following URLs not to be cached, when/if you are serving Element from your own webserver:
/config.*.json
/i18n
/version
/index.html
We also recommend that you force browsers to re-validate any cached copy of Element on page load by configuring your
webserver to return Cache-Control: no-cache for /. This ensures the browser will fetch a new version of Element on
the next page load after it's been deployed. Note that this is already configured for you in the nginx config of our
Dockerfile.
Development
Please read through the following:
Extending Element Web with Modules
Element Web supports a module system that allows you to extend or modify functionality at runtime. Modules are loaded dynamically and provide a safe, predictable API for customization.
What are modules?
Modules are extensions that can add or modify Element Web's functionality. They are:
- Built using the
@element-hq/element-web-module-api - Loaded in EW via config.json