From 3d94420f9f5f25f8c4cc5bf410cb5d7a5d9465cd Mon Sep 17 00:00:00 2001
From: Michael Telatynski <7t3chguy@gmail.com>
Date: Wed, 29 Jan 2025 09:02:46 +0000
Subject: [PATCH] Iterate

---
 packages/element-web-module-api/README.md | 48 +++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/packages/element-web-module-api/README.md b/packages/element-web-module-api/README.md
index 35572c1394..b5cdac7d96 100644
--- a/packages/element-web-module-api/README.md
+++ b/packages/element-web-module-api/README.md
@@ -4,6 +4,54 @@ API surface for extending Element Web in a safe & predictable way.
 
 This project is still in early development but aims to replace matrix-react-sdk-module-api and Element Web deprecated customisations.
 
+## Using the API
+
+Modules are loaded by Element Web at runtime via a dynamic ecmascript import, but can be bundled into a webapp for deployment convenience.
+
+The module's default export MUST be a class which accepts a single argument, an instance of `ModuleApi`.
+This class must also bear a static property `moduleApiVersion` which is a semver range string
+and a `load` method which is called when the module is to be loaded.
+
+```typescript
+import type { Module, Api, ModuleFactory } from "@element-hq/element-web-module-api";
+
+class ExampleModule implements Module {
+    public static readonly moduleApiVersion = "^0.1.0";
+
+    public constructor(private api: Api) {}
+
+    public async load(): Promise<void> {
+        // Your extension code goes here
+    }
+}
+
+export default ExampleModule satisfies ModuleFactory;
+```
+
+### Accessing application configuration
+
+The `api` object passed to the module constructor provides access to the application configuration.
+You can extend the Config types using declaration merging, though please ensure that you do not trust the types you specify,
+and opt for runtime validation due to the dynamic nature of the configuration.
+
+```typescript
+// ...
+declare module "@element-hq/element-web-module-api" {
+    interface Config {
+        "this.is.my.config.key": string;
+    }
+}
+
+class ExampleModule implements Module {
+    // ...
+    public async load(): Promise<void> {
+        const configValue = this.api.config.get("this.is.my.config.key");
+        // Your extension code goes here
+    }
+}
+// ...
+```
+
 ## Copyright & License
 
 Copyright (c) 2025 New Vector Ltd