diff --git a/README.md b/README.md index 32bb906c4..493ed90c9 100644 --- a/README.md +++ b/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 diff --git a/index-wasm-esm.mjs b/index-wasm-esm.mjs new file mode 100644 index 000000000..8015d9b00 --- /dev/null +++ b/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} + */ +export async function initAsync() {} + +// Re-export everything from the generated javascript wrappers +export * from "./pkg/matrix_sdk_crypto_wasm_bg.js"; diff --git a/index.mjs b/index.mjs index bf8df6702..be247fe7d 100644 --- a/index.mjs +++ b/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. */ diff --git a/package.json b/package.json index 09aecfed9..9b2d22b98 100644 --- a/package.json +++ b/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",