Element Web: self-hosting the Matrix client, and where it stops

What Element Web solves, and for whom

Matrix is a protocol, not a product. Someone has to ship a client that speaks it, and Element Web is that client for the browser: it is described in the README as a Matrix web and desktop client built using the Matrix JS SDK, formerly known as Vector and Riot. The audience is narrower than the download page suggests. This is for organisations that already operate a Matrix homeserver and want a browser-based front end their users can open without installing anything, and for developers who need to read or extend a large, real-world TypeScript client rather than a toy example. It is not a hosted service you sign up for. The README points casual users at the hosted copy at app.element.io and says the easiest way to test Element is to use it, which is a fair signal about who the self-hosted path is actually for.

The monorepo layout and how a page becomes a message

This repository is not a single app. The README states plainly that it is a monorepo hosting Element Web and other related projects in various subdirectories, with the structure described in docs/monorepo.md. The top level carries apps/, packages/, modules/ and scripts/ alongside a pnpm-workspace.yaml, so the web client lives under apps/web and shared code is published from packages/. The data flow is the part worth understanding before you deploy: Element Web is a rendering and state layer over the Matrix JS SDK, which holds the client-server connection to a homeserver. The client does not store your message history authoritatively; the homeserver does, and the SDK syncs room state and events into the browser. That single fact explains most operational behaviour, including why a slow or unreachable homeserver makes the UI feel broken and why clearing browser storage does not delete your rooms. The package.json confirms the toolchain: type module, Nx for task running, Vitest for unit tests, Playwright for end-to-end, oxlint and oxfmt for linting and formatting, and a postinstall script that runs scripts/pnpm-link.ts.

Installing Element Web and pointing it at a homeserver

The README does not put install commands in the top level file. It says to host your own instance you should see docs/install.md, and that the desktop build instructions live in apps/desktop. What the repository does expose is the workspace tooling, which is pnpm-based. The root package.json declares a postinstall step that links packages and runs sane-postinstall across the workspace, so a plain install is doing real work beyond fetching dependencies. The command below is the documented entry point for that. Expect the postinstall script to run and to see the workspace packages linked before the command returns.

Running the test and lint tasks before you deploy

Once dependencies are in place, the repository exposes the standard task scripts at the root. Unit tests run through Nx preparation followed by Vitest, and the lint script chains type checking, formatting, JavaScript linting, style linting, workflow validation and knip in that order. Running the test script is the fastest way to confirm your local toolchain matches what CI expects.

Deploying from the docs rather than from the README

For an actual deployment, the README's instruction is to read docs/install.md, and the repository root contains docker-bake.hcl, which indicates a Docker-based build path exists. The README also documents that the develop branch is continuously deployed to develop.element.io, so you can compare your build against a known-good instance. What the README does not give is a ready-made docker run command with a port and image tag, so do not assume one; take the image name and configuration keys from docs/install.md and docs/config.md rather than from this article. The configuration docs are the file to read before your first deploy, because the client needs to know which homeserver to talk to and that is a deployment decision, not a build-time one.

The support tiers are the real constraint

Most client projects have a vague browser policy. Element Web publishes an explicit four-tier one, and it is the most useful thing in the README for anyone planning a rollout. Supported means the last two major versions of Chrome, Firefox and Edge on desktop, the last two versions of Safari, and the latest official Element Desktop release; issues there are actively triaged and regressions block the release. Best effort covers the last major release of Firefox ESR and Chrome or Edge Extended Stable, where issues are accepted but regressions do not block. Community supported covers mobile web for current stable Chrome, Firefox and Safari on Android, iOS and iPadOS, where community contributions are welcome but nothing is guaranteed. Everything else is not supported, and the README states that issues only affecting unsupported environments are closed. That last clause matters: if your users are on an older enterprise browser, a bug report is not a request, it is a closed ticket. The README also recommends the native element-x-android and element-x-ios apps for mobile rather than this client, which is an unusually direct admission that the web build is not the right answer on phones.

What Element Web is not good at

The licence situation deserves a clear-eyed look before adoption. The README describes the software as multi licensed and offers three routes: AGPL-3.0, GPL-3.0, or a paid Element Commercial License negotiated with Element. That is a genuine choice rather than a formality, and the AGPL route carries obligations that matter if you modify the client and expose it to users over a network. This is not legal advice; the point is that the licence is a deployment decision you should settle early, and the README directs commercial enquiries to [email protected]. The second limitation is structural. Element Web needs a homeserver you control or trust, and the README gives no guidance on operating one, because that is a separate project. Teams expecting a self-contained chat product will find themselves maintaining two systems. The third is that this is a monorepo under continuous development on the develop branch, with a release cadence visible in the version history; if you fork it, you are forking a moving target with Nx, pnpm workspaces and a patched-dependency directory to keep in sync.

Element Web against a hosted chat product

The honest comparison is not Element Web versus another web client, it is Element Web versus a hosted service such as Slack or Discord. The difference is where the data lives and who operates the service. A hosted product gives you an account and an API; Element Web gives you a client and expects you to bring a homeserver, which is why the README's first instruction is to use app.element.io if you just want to try it. The trade is control for operational burden. Within the Matrix ecosystem the alternative to Element Web is a different client speaking the same protocol against the same homeserver, which means switching clients does not require migrating your message history. That is a real advantage over the hosted-product comparison, and it is the reason the support-tier and configuration details matter more here than they would for a closed client.

Maintenance, releases and upgrade cost

The repository is not archived, and the last push was on 2026-09-21. The recent release history shows v1.12.28 on 2026-09-16 alongside module releases widget-toggles v1.1.0 and widget-lifecycle v1.1.0 on 2026-09-18, which indicates the monorepo ships the web app and its modules on separate tracks. The README states that the period of support for each environment tier lasts until the releases specified, plus one app release cycle of two weeks, extended for Firefox ESR so it lands in Debian Stable. That two-week cycle is the upgrade cost in concrete terms: if you self-host, you are choosing how far behind that cadence to sit, and the support window assumes you do not sit far behind. The root lint script runs type checking, formatting, JavaScript linting, style linting, workflow validation and knip in sequence, so a fork that drifts will feel that chain on every merge. On licensing, the three-option scheme in the README means the upgrade cost is not only technical; the commercial route exists precisely for deployments where the AGPL or GPL terms do not fit.

Editorial conclusion

Adopt Element Web if you already run a Matrix homeserver and want the client that the Matrix ecosystem treats as the reference implementation, or if you need a desktop build via Electron. Do not adopt it as a Slack or Discord replacement for non-technical users who will not tolerate a homeserver to operate, and do not deploy it to mobile web expecting support, because the README classifies mobile web as community supported and points Android and iOS users at the native Element X apps. Before you commit, verify which support tier your browsers fall into, read docs/config.md for the settings your deployment needs, and confirm with [email protected] whether the AGPL-3.0 path or the commercial licence fits how you distribute the app.

Frequently asked questions

Official sources

1. element-hq/element-web on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases