David LangleyandGitHub
a0639bfc4b
* Forward the scroller element and scroll handle through VirtualizedList The room list needs two things the generic list did not expose: the underlying scroll container (to observe which items are genuinely visible) and the imperative scroll handle (to scroll an item into view). Forward an optional scrollerRef from useVirtualizedList and pass scrollHandleRef through FlatVirtualizedList, mirroring what GroupedVirtualizedList already exposes. Both are additive and optional, so other consumers are unaffected. Signed-off-by: David Langley <langley.dave@gmail.com> * Add an unread-activity toast to the room list Show a clickable "You have unread activity" pill when there are unread rooms scrolled below the visible fold, including unreads hidden inside collapsed sections whose header is below the fold. Clicking it scrolls the next such unread into view. The visible fold is tracked with an IntersectionObserver over the rendered item elements, so the toast appears as soon as a room crosses the fold rather than only once it leaves Virtuoso's overscan buffer. The toast click is wired through an imperative scroll handle the view registers with the view model. Signed-off-by: David Langley <langley.dave@gmail.com> * Change toast to target notifications only, not unread activity. * Fix formatting and refresh Toast snapshots for compound-web 9.7.0 - Apply oxfmt to the room list view model and virtualized view. - Refresh the RoomListToast/RoomListView story snapshots: compound-web 9.7.0 moves the typography classes onto the toast .content element and rebuilds the Toast CSS module hashes. - Add the missing UnreadActivityToast render snapshot baseline. * Add e2e tests for the room list unread activity toast Cover the unread-activity toast end to end: - it appears for a notifying room scrolled below the fold and clicking it scrolls that room into view (then the toast clears); - a room with only an unread-activity dot (no notification count) does not raise it; - a collapsed section hiding a notifying room raises it, and clicking scrolls the section header into view. * Add visual snapshot baselines for the unread-activity toast stories * Converge room-list toast codepaths into a single state-driven toast Reviewer feedback: the unread-activity toast and the transient event toasts (section_created / chat_moved) should share one mechanism, with toast lifecycle and precedence owned by the view model rather than split across a separate snapshot flag and a view-level ternary. - RoomListViewModel now reconciles the transient event toast and the derived unread-activity state into a single snapshot.toast via recomputeToast(); the event toast still takes precedence and auto-dismisses, and the unread toast reappears once it clears. Drops hasUnreadActivityBelow from the snapshot. - RoomListView renders a single RoomListToast driven by snapshot.toast; the ToastType union gains 'unread_activity'. The standalone UnreadActivityToast component is folded into RoomListToast (clickable arrow-down variant). - Adds VM tests for the unread-activity toast and the event/unread precedence. * Pre-bundle the room-list dnd-kit + virtuoso graph in vitest browser mode The room-list suites (RoomListView, VirtualizedRoomListView, RoomListItemMoreOptionsMenu) import a heavy @dnd-kit + react-virtuoso graph. Only @dnd-kit/abstract was pinned in optimizeDeps.include; @dnd-kit/dom, @dnd-kit/react, @dnd-kit/abstract/modifiers and react-virtuoso were left to runtime discovery. Under CI load the browser-mode dep optimizer can discover them late, re-bundle and reload the page, which fails the in-flight setupTests.ts import for those suites. Pinning the whole graph forces it into the initial optimize pass so no re-run happens while tests load. --------- Signed-off-by: David Langley <langley.dave@gmail.com>
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