Add Element Module for Hookshot

changelog.d/1064.feature

@@ -0,0 +1 @@
+Add Element Web/Desktop module for pretty rendering of Hookshot information.

docs/SUMMARY.md

@@ -31,4 +31,5 @@
 - [Workers](./advanced/workers.md)
 - [🔒 Encryption](./advanced/encryption.md)
 - [🪀 Widgets](./advanced/widgets.md)
+- [Element Web Integration](./advanced/element_module.md)
 - [Service Bots](./advanced/service_bots.md)

docs/advanced/element_module.md

@@ -0,0 +1,20 @@
+# Element Module
+
+<section class="warning">
+Element Modules are very much in the early stages of development, and Hookshot is using bleeding edge APIs.
+Please be aware that breakages are likely until the APIs become more stable.
+</section>
+
+Hookshot provides a module that can be used by Element Web / Element Desktop to render
+additional information below an event that has come from Hookshot. You will need to be
+able to edit your Element's `config.json` for this feature to work.
+
+This may be enabled by adding the module's URL to your Element Web `config.json` file.
+See [Element Web's documentation](https://github.com/element-hq/element-web/blob/develop/docs/config.md) for how this works.
+
+The Hookshot module will be found under `/elementModule/index.mjs` on the `widgets` listener. For instance
+if you host your widgets listener on `https://hookshot.example.org/widgets` then the path would be `https://hookshot.example.org/widgets/elementModule/index.mjs`.
+
+At the time of writing, this is supported for a subset of integrations:
+
+- OpenProject: Work package previews.

package.json

@@ -13,7 +13,9 @@
     "node": ">=22"
   },
   "scripts": {
-    "build:web": "vite build",
+    "build:web": "yarn build:web:widget && yarn build:web:elementmodule",
+    "build:web:widget": "vite build",
+    "build:web:elementmodule": "vite --config vite.elementmodule.mjs build",
     "build:app": "tsc --project tsconfig.json",
     "build:app:rs": "napi build --dts ../src/libRs.d.ts --release ./lib",
     "build:app:fix-defs": "ts-node scripts/definitions-fixer.ts src/libRs.d.ts",
@@ -86,6 +88,7 @@
   "devDependencies": {
     "@babel/core": "^7.26.9",
     "@codemirror/lang-javascript": "^6.0.2",
+    "@element-hq/element-web-module-api": "^1.0.0",
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.15.0",
     "@fontsource/inter": "^5.1.0",
@@ -106,8 +109,10 @@
     "@types/mime": "^3.0.4",
     "@types/mocha": "^10.0.6",
     "@types/node": "^22",
+    "@types/react": "^19",
     "@types/xml2js": "^0.4.11",
     "@uiw/react-codemirror": "^4.12.3",
+    "@vitejs/plugin-react": "^4.3.4",
     "busboy": "^1.6.0",
     "chai": "^4",
     "eslint": "^9.15.0",
@@ -118,13 +123,19 @@
     "nyc": "^17.1.0",
     "preact": "^10.26.2",
     "prettier": "^3.5.3",
+    "react": "^19",
+    "react-dom": "^19",
     "rimraf": "6.0.1",
+    "rollup-plugin-external-globals": "^0.13.0",
     "sass": "^1.81.0",
+    "styled-components": "^6.1.18",
     "testcontainers": "^10.25.0",
     "ts-node": "10.9.2",
-    "typescript": "^5.7.2",
+    "typescript": "^5.7.3",
     "typescript-eslint": "^8.16.0",
-    "vite": "^5.4.19",
+    "vite": "^6.1.6",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-node-polyfills": "^0.23.0",
     "vitest": "^3.1.3"
   },
   "packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"

vite.elementmodule.mjs

@@ -0,0 +1,39 @@
+import { resolve } from "node:path";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { nodePolyfills } from "vite-plugin-node-polyfills";
+import externalGlobals from "rollup-plugin-external-globals";
+import dts from "vite-plugin-dts";
+
+export default defineConfig({
+    build: {
+        lib: {
+            entry: resolve("web", "elementModule", "index.tsx"),
+            name: "hookshot-openproject",
+            fileName: "index",
+            formats: ["es"],
+        },
+        outDir: "public/elementModule",
+        target: "esnext",
+        sourcemap: true,
+        rollupOptions: {
+            external: ["react"],
+        },
+    },
+    plugins: [
+        dts({tsconfigPath: resolve("web", "elementModule", "tsconfig.json")}),
+        react(),
+        nodePolyfills({
+            include: ["events"],
+        }),
+        externalGlobals({
+            // Reuse React from the host app
+            react: "window.React",
+        }),
+    ],
+    define: {
+        // Use production mode for the build as it is tested against production builds of Element Web,
+        // this is required for React JSX versions to be compatible.
+        process: { env: { NODE_ENV: "production" } },
+    },
+});