matrix-widget-api

matrix-widget-api is the official JavaScript/TypeScript SDK for the Matrix widget protocol. Widgets are embedded web applications inside a Matrix client, and this library defines the two-way, capability-based messaging channel that lets a widget and its host client talk to each other safely over postMessage.

It provides high-level WidgetApi (widget side) and ClientWidgetApi (client side) classes that handle capability negotiation, action dispatch, and transport, along with the typed interfaces and drivers needed to build widgets or to host them in a Matrix client.

What You Get

• A WidgetApi class for the widget side to request capabilities and send/receive actions.
• A ClientWidgetApi class for the host client to drive and respond to widgets.
• Capability negotiation primitives for scoping what a widget is allowed to do.
• Typed action interfaces and a transport layer over postMessage.

Common Use Cases

• Building an embedded widget (e.g. a video conference or dashboard) for a Matrix client.
• Adding widget hosting support to a Matrix client application.
• Negotiating and enforcing capabilities between a widget and its host.

Under The Hood

Architecture

The src tree splits into WidgetApi.ts and ClientWidgetApi.ts (the two public entry points), a transport layer that correlates request/response messages over postMessage, interfaces and models describing actions and capabilities, and driver abstractions the host implements. Events are dispatched through an EventEmitter, letting consumers handle action:* events.

Tech Stack

Written in TypeScript, compiled to both CommonJS/ESM libraries and a browser UMD bundle. Its only runtime dependency is events (with @types/events); build and test tooling uses tsc, Jest, ESLint, and Prettier.

Code Quality

The project maintains a test suite run under Jest, ESLint and Prettier enforcement, SonarQube configuration, and a documented docs/examples folder. Being TypeScript-first, the action and capability contracts are statically typed end to end.

API Design

The API guides developers into the correct sequence: construct a WidgetApi, request capabilities, then start it. Handlers are registered as action:<name> event listeners, which is idiomatic for JS but does require reading the docs to learn the capability and action vocabulary, giving it a moderate learning curve for a niche protocol.