Absorb element-modules/packages/element-web-module-api into monorepo

.github/workflows/npm-publish.yaml

@@ -10,6 +10,7 @@ on:
                 options:
                     - playwright-common
                     - shared-components
+                    - module-api
 
 concurrency: release
 jobs:

.github/workflows/tests.yml

@@ -100,7 +100,7 @@ jobs:
 
     complete:
         name: jest-tests
-        needs: [jest_ew, vitest_sc]
+        needs: [jest_ew, vitest]
         if: always()
         runs-on: ubuntu-24.04
         permissions:
@@ -120,8 +120,13 @@ jobs:
                   sha: ${{ github.sha }}
                   target_url: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}
 
-    vitest_sc:
-        name: Vitest (Shared Components)
+    vitest:
+        name: Vitest
+        strategy:
+            matrix:
+                package:
+                    - shared-components
+                    - module-api
         runs-on: ubuntu-24.04
         steps:
             - name: Checkout code
@@ -137,32 +142,32 @@ jobs:
                   node-version: "lts/*"
                   cache: "pnpm"
 
-            - name: Install Shared Component Deps
-              working-directory: "packages/shared-components"
+            - name: Install Deps
               run: "pnpm install"
 
             - name: Cache storybook & vitest
               uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5
               with:
                   path: |
-                      packages/shared-components/node_modules/.cache
-                      packages/shared-components/node_modules/.vite/vitest
+                      packages/${{ matrix.package }}/node_modules/.cache
+                      packages/${{ matrix.package }}/node_modules/.vite/vitest
                   key: ${{ hashFiles('pnpm-lock.yaml') }}
 
             - name: Setup playwright
               uses: ./.github/actions/setup-playwright
+              if: matrix.package == 'shared-components'
               with:
                   write-cache: ${{ github.event_name != 'merge_group' }}
 
             - name: Run tests
-              working-directory: "packages/shared-components"
+              working-directory: "packages/${{ matrix.package }}"
               run: pnpm test:unit --coverage=$ENABLE_COVERAGE
 
             - name: Upload Artifact
               if: env.ENABLE_COVERAGE == 'true'
               uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7
               with:
-                  name: coverage-sharedcomponents
+                  name: coverage-${{ matrix.package }}
                   path: |
-                      packages/shared-components/coverage
-                      !packages/shared-components/coverage/lcov-report
+                      packages/${{ matrix.package }}/coverage
+                      !packages/${{ matrix.package }}/coverage/lcov-report

.prettierignore

@@ -14,7 +14,8 @@ webpack-stats.json
 .vscode/
 .env
 coverage
-# Auto-generated file
+# Auto-generated files
+*.api.md
 /apps/web/src/modules.ts
 /apps/web/src/modules.js
 src/i18n/strings

apps/web/Dockerfile.dockerignore

@@ -10,6 +10,7 @@
 **/.pnpm-store
 **/tsconfig.node.tsbuildinfo
 **/*.md
+!**/*.api.md
 **/*.rst
 
 .idea/

apps/web/package.json

@@ -38,7 +38,7 @@
     },
     "dependencies": {
         "@babel/runtime": "^7.12.5",
-        "@element-hq/element-web-module-api": "catalog:",
+        "@element-hq/element-web-module-api": "workspace:*",
         "@element-hq/web-shared-components": "workspace:*",
         "@fontsource/fira-code": "^5",
         "@fontsource/inter": "catalog:",

knip.ts

@@ -14,6 +14,7 @@ export default {
             ],
             ignoreBinaries: ["awk"],
         },
+        "packages/module-api": {},
         "apps/web": {
             entry: [
                 "src/serviceworker/index.ts",

packages/module-api/.gitignore

@@ -0,0 +1,2 @@
+lib/
+temp/

packages/module-api/Dockerfile

@@ -0,0 +1,24 @@
+ARG ELEMENT_VERSION=latest@sha256:a84f294ce46e4327ebacecb78bfc94cf6a45c7ffa5104a28f06b5ac69d0b2548
+
+FROM --platform=$BUILDPLATFORM node:lts-alpine@sha256:01743339035a5c3c11a373cd7c83aeab6ed1457b55da6a69e014a95ac4e4700b AS builder
+
+ARG BUILD_CONTEXT
+
+RUN apk add --no-cache jq
+
+WORKDIR /app
+COPY package.json yarn.lock ./
+# Copy the package.json files of all modules & packages to ensure the frozen workspace lockfile holds up
+RUN --mount=type=bind,target=/docker-context \
+    cd /docker-context/; \
+    find . -path ./node_modules -prune -o -name "package.json" -mindepth 0 -maxdepth 4 -exec cp --parents "{}" /app/ \;
+RUN yarn install --frozen-lockfile --ignore-scripts
+COPY tsconfig.json ./
+COPY ./$BUILD_CONTEXT ./$BUILD_CONTEXT
+RUN cd $BUILD_CONTEXT && yarn vite build
+RUN mkdir /modules
+RUN cp -r ./$BUILD_CONTEXT/lib/ /modules/$(jq -r '"\(.name)-v\(.version)"' ./$BUILD_CONTEXT/package.json)
+
+FROM ghcr.io/element-hq/element-web:${ELEMENT_VERSION}
+
+COPY --from=builder /modules /modules/

packages/module-api/README.md

@@ -0,0 +1,68 @@
+# @element-hq/element-web-module-api
+
+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
+    }
+}
+// ...
+```
+
+## Releases
+
+The API is versioned using semver, with the major version incremented for breaking changes.
+
+## Copyright & License
+
+Copyright (c) 2025 New Vector Ltd
+
+This software is multi licensed by New Vector Ltd (Element). It can be used either:
+
+(1) for free under the terms of the GNU Affero General Public License (as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version); OR
+
+(2) under the terms of a paid-for Element Commercial License agreement between you and Element (the terms of which may vary depending on what you and Element have agreed to).
+Unless required by applicable law or agreed to in writing, software distributed under the Licenses is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licenses for the specific language governing permissions and limitations under the Licenses.