117 lines
5.6 KiB

# Matrix Viewer
<a href=""><img src="" alt="Join the community and get support at" /></a>
> **Note**
> The Matrix Public Archive has been renamed to Matrix Viewer to better reflect what it
> actually does and doesn't do. It's a viewer for world-readable Matrix rooms and
> doesn't actually archive anything.
In the vein of [feature parity with
Gitter](, the goal is to make an
accessible public site for `world_readable` Matrix rooms like Gitter's archives
which search engines can index and keep all of the content accessible/available.
<!-- prettier-ignore -->
Room directory homepage | Room view
--- | ---
<img alt="A reference for how the Matrix Viewer homepage looks. Search bar where you can find thousands of rooms using Matrix and homeserver selector. Grid of room cards showing the results." src="" width="440"> | ![A reference for how the Matrix Viewer looks. Showing off a day of messages in `` on 2021-08-06. There is a date picker calendar in the right sidebar and a traditional chat app layout on the left.](
## Demo videos
The demo's refer to this project as the "Matrix Public Archive" which has now been renamed to "Matrix Viewer".
- [![]( May 2023]( Introducing [](, the shiny new public instance of the Matrix Public Archive that everyone can share and link to.
- [![]( Aug 2022]( ([blog post]( A quick intro of what the project looks like, the goals, what it accomplishes, and how it's a new portal into the Matrix ecosystem.
- [![]( Oct 2022]( Showing off the room directory landing page used to browse everything available in the archive.
## Technical overview
We server-side render (SSR) the [Hydrogen](
Matrix client on a Node.js server (since both use JavaScript) and serve pages on the fly
(with some Cloudflare caching on top) when someone requests
`/r/${year}/${month}/${day}`. To fetch the events for a
given day/time, we use [MSC3030]('s
`/timestamp_to_event` endpoint to jump to a given day in the timeline and fetch the
messages from a Matrix homeserver.
Re-using Hydrogen gets us pretty and native(to Element) looking styles and keeps
the maintenance burden of supporting more event types in Hydrogen.
## FAQ
See the [FAQ page](docs/
## Setup
### Prerequisites
- [Node.js]( v18
- We need v18 because it includes `fetch` by default. And [`node-fetch` doesn't
support `abortSignal.reason`](
- We need v16 because it includes
for [Matrix encryption (olm) which can't be disabled in
Hydrogen]( yet. And
[`abortSignal.reason` was introduced in
v16.14.0]( (although we use `node-fetch` for now).
- A Matrix homeserver that supports [MSC3030's]( `/timestamp_to_event` endpoint
- [Synapse]( 1.73.0+
### Get the app running
$ npm install
$ npm run build
# Edit `config/config.user-overrides.json` so that `matrixServerUrl` points to
# your homeserver and has `matrixAccessToken` defined
$ cp config/config.default.json config/config.user-overrides.json
$ npm run start
## Development
# Clone and install the `matrix-viewer` project
$ git clone
$ cd matrix-viewer
$ npm install
# Edit `config/config.user-overrides.json` so that `matrixServerUrl` points to
# your homeserver and has `matrixAccessToken` defined
$ cp config/config.default.json config/config.user-overrides.json
# This will watch for changes, rebuild bundles and restart the server
$ npm run start-dev
If you want to make changes to the underlying Hydrogen SDK as well, you can locally link
it into this project with the following instructions:
# We need to use a draft branch of Hydrogen to get the custom changes needed for
# `matrix-viewer` to run. Hopefully soon, we can get all of the custom
# changes mainlined so this isn't necessary.
$ git clone
$ cd hydrogen-web
$ git checkout madlittlemods/matrix-public-archive-scratch-changes
$ yarn install
$ yarn build:sdk
$ cd target/ && npm link && cd ..
$ cd ..
$ cd matrix-viewer
$ npm link hydrogen-view-sdk
### Running tests
See the [testing documentation](./docs/
### Tracing
See the [tracing documentation](./docs/