Add another entrypoint using wasm-as-esm support

README.md

@@ -53,7 +53,28 @@ Encryption](https://en.wikipedia.org/wiki/End-to-end_encryption)) for
     }
     ```
 
-## Building
+    See the [API documentation](https://matrix-org.github.io/matrix-rust-sdk-crypto-wasm/) for more information.
+
+3. Build your project.
+
+    The packaging of this library aims to "just work" the same as any plain-javascript project would: it includes
+    separate entry points for Node.js-like environments (which read the WASM file via
+    [`fs.readFile()`](https://nodejs.org/api/fs.html#fsreadfilepath-options-callback)) and web-like environments (which
+    download the WASM file with [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch)). There are
+    both CommonJS and ES Module entry points for each environment; an appropriate entrypoint should be selected
+    automatically.
+
+    If your environment supports the experimental [ES Module Integration Proposal for WebAssembly](https://github.com/WebAssembly/esm-integration),
+    you can instead use that, by setting the `matrix-org:wasm-esm` custom [export condition](https://nodejs.org/api/packages.html#conditional-exports).
+    This is only supported when the library is imported as an ES Module. For example:
+
+    - In Webpack, set [`experiments.asyncWebAssembly`](https://webpack.js.org/configuration/experiments/#experiments)
+      to `true` and [`resolve.conditionNames`](https://webpack.js.org/configuration/resolve/#resolveconditionnames)
+      to `["matrix-org:wasm-esm", "..."]` (the `"..."` preserves default condition names).
+    - In Node.js, invoke with commandline arguments [`--experimental-wasm-modules`](https://nodejs.org/api/esm.html#wasm-modules)
+      [`--conditions=wasm-esm`](https://nodejs.org/api/cli.html#-c-condition---conditionscondition).
+
+## Building matrix-sdk-crypto-wasm
 
 These WebAssembly bindings are written in [Rust]. To build them, you
 need to install the Rust compiler, see [the Install Rust

index-wasm-esm.mjs

@@ -0,0 +1,39 @@
+// Copyright 2024 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// @ts-check
+
+/**
+ * This is the entry point for ESM environments which support the ES Module Integration Proposal for WebAssembly [1].
+ *
+ * [1]: https://github.com/webassembly/esm-integration
+ */
+
+import * as bindings from "./pkg/matrix_sdk_crypto_wasm_bg.js";
+
+/** @type {typeof import("./pkg/matrix_sdk_crypto_wasm_bg.wasm.d.ts")} */
+// @ts-expect-error TSC can't find the definitions file, for some reason.
+const wasm = await import("./pkg/matrix_sdk_crypto_wasm_bg.wasm");
+bindings.__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+
+/**
+ * A no-op, for compatibility with other entry points.
+ *
+ * @returns {Promise<void>}
+ */
+export async function initAsync() {}
+
+// Re-export everything from the generated javascript wrappers
+export * from "./pkg/matrix_sdk_crypto_wasm_bg.js";

index.mjs

@@ -15,7 +15,7 @@
 // @ts-check
 
 /**
- * This is the entrypoint on non-node ESM environments (such as Element Web).
+ * This is the entrypoint on non-node ESM environments.
  * `asyncLoad` will load the WASM module using a `fetch` call.
  */
 

package.json

@@ -20,6 +20,10 @@
     ],
     "exports": {
         ".": {
+            "matrix-org:wasm-esm": {
+                "types": "./index.d.ts",
+                "default": "./index-wasm-esm.mjs"
+            },
             "require": {
                 "types": "./index.d.ts",
                 "node": "./node.js",