Matrix Widget Toolkit

Reusable framework for creating Matrix widgets.

This repository contains multiple packages that provide reusable components that can be used to write Matrix/Element widgets.

• @matrix-widget-toolkit/api: A package that wraps matrix-widget-api to provide a more convenient API.
• @matrix-widget-toolkit/react: A package that provides a Widget API integration for React apps.
• @matrix-widget-toolkit/mui: A package that provides a matching Mui theme for Element.
• @matrix-widget-toolkit/testing: Vitest Testing support for @matrix-widget-toolkit/api.
• @matrix-widget-toolkit/widget-server: A container to host a Matrix widget in a production environment.
• More packages to follow…

Background

Nordeck is developing multiple widgets that are all based on the matrix-widget-api. This collection of packages shares the common parts of our widgets:

• Advanced patterns using the matrix-widget-api, providing an API that better fits our use cases.
• Integrating it into React applications.
• Provide a common theming that integrates well with Element (the only Matrix client that supports the matrix-widget-api up to now).
• Testing support

Notable Projects

Many projects have been built using this framework. Here is a list of the ones we consider to be a great showcase of what is possible to achieve with it:

• NeoBoard: A collaborative whiteboard widget for Matrix
• NeoDateFix: A solution to organizing meetings in Matrix chat rooms and video conferences
• Matrix Poll: This widget allows to conduct polls in Matrix rooms.
• Matrix BarCamp: A widget for organizing Barcamps in Matrix chat rooms
• Beeper Widgets: Widgets within the Beeper unified messaging app.

Getting Started

This repository contains an example widget that shows the usage of the packages.

How to Contribute

Please take a look at our Contribution Guidelines. Check the following steps to develop for the packages:

Requirements

You need to install Node.js (>= 20.0.0) and run yarn to work on this package. We officially only support the latest Node.js LTS, but different versions may also work.

Installation

After checkout, run yarn install to download the required dependencies.

Warning

Do not use npm install when working with this package.

Available Scripts

The following commands are available:

• yarn dev:example: Start the example app.
• yarn dev:example:https: Start the example app with a self-signed HTTPS certificate.
• yarn build: Build all packages and the example app.
• yarn preview:example: Preview a built version of the example app. Requires yarn build to be run first.
• yarn preview:example:https: Preview a built version of the example app with a self-signed HTTPS certificate. Requires yarn build to be run first.
• yarn test: Watch all packages for changes and run tests.
• yarn tsc: Check TypeScript types for errors in all packages.
• yarn lint: Run eslint on all packages.
• yarn prettier:write: Run prettier on all files to format them.
• yarn depcheck: Check all packages for missing or unused dependencies.
• yarn deduplicate: Deduplicate dependencies in the yarn.lock file.
• yarn changeset: Generate a changeset that provides a description of a change.
• yarn translate: Update translation files from code.
• yarn generate-api-report: Every time you change the public API interface, you have to update the api-report.md of the related package using this script. The API report provides an overview about the exported elements of the package.
• yarn clean: Cleans builds and caches
• yarn clean:build: Cleans builds
• yarn clean:cache: Cleans caches

Deploying the Example Widget to Netlify

The example widget can be deployed to Netlify for testing with Element or other Matrix clients. The configuration is in netlify.toml.

To deploy:

1. Connect your repository to Netlify:

   • Go to Netlify
   • Add a new site from Git
   • Select this repository

2. Configure build settings:

   • Netlify will automatically detect netlify.toml in the repository root
   • The configuration builds only the example widget (@matrix-widget-toolkit/example-widget-mui)
   • No additional configuration needed in the Netlify UI

3. Environment variables (optional):

   • If you need any REACT_APP_* environment variables, add them in Netlify's site settings

4. Deploy:

   • Push to your branch or trigger a deploy manually
   • Netlify will build and deploy the widget

The deployed widget will have:

• Valid HTTPS certificate (required by Matrix clients)
• CORS headers configured for embedding
• SPA routing support for React Router

Use the Netlify URL in your Element client to test the widget. The widget URL will be something like https://your-site.netlify.app.

Versioning

All packages use automated versioning. Each change should be accompanied with a specification of the impact (patch, minor, or major) and a description of the change. Use yarn changeset to generate a new changeset for the project you touch in a pull request. Learn more in the .changeset folder.

Once the change is merged to main, a "Version Packages" pull request will be created. As soon as that is merged, the packages will be released to the package registry.

Processing Renovate PRs

Renovate PRs which update packages that are direct dependencies of our packages (and not devDependencies or only a dependency of the example widget) need a changeset as described above. Specify the impact as patch.

Architecture Decision Records

We use Architecture Decision Records (ADR)s to document decisions for our software. You can find them at /docs/adrs.

License

This project is licensed under the Apache 2.0 license.