feat: support ?module suffix for compatibility

README.md

@@ -76,6 +76,18 @@ await initRand({
 > [!NOTE]
 > When using **static import syntax**, and before initializing the module, the named exports will be wrapped into a function by proxy that waits for the module initialization and if called before init, will immediately try to call init without imports and return a Promise that calls a function after init.
 
+### Module compatibility
+
+There are situations where libraries require a [`WebAssembly.Module`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Module) instance to initialize [`WebAssembly.Instance`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Instance/Instance) themselves. In order to maximize compatibility, unwasm allows a specific import suffix `?module` to import `.wasm` files as a Module directly.
+
+```js
+import _sumMod from "unwasm/examples/sum.wasm?module";
+const { sum } = await WebAssembly.instantiate(_sumMod).then((i) => i.exports);
+```
+
+> [!NOTE]
+> Open [an issue](https://github.com/unjs/unwasm/issues/new/choose) to us! We would love to help those libraries to migrate!
+
 ## Integration
 
 Unwasm needs to transform the `.wasm` imports to the compatible bindings. Currently, the only method is using a rollup plugin. In the future, more usage methods will be introduced.

src/plugin/index.ts

@@ -12,10 +12,16 @@ import {
  UnwasmPluginOptions,
  WasmAsset,
 } from "./shared";
-import { getPluginUtils, getWasmBinding } from "./runtime";
+import {
+ getPluginUtils,
+ getWasmESMBinding,
+ getWasmModuleBinding,
+} from "./runtime";
 
 export type { UnwasmPluginOptions } from "./shared";
 
+const WASM_ID_RE = /\.wasm\??.*$/i;
+
 const unplugin = createUnplugin<UnwasmPluginOptions>((opts) => {
  const assets: Record<string, WasmAsset> = Object.create(null);
 
@@ -63,7 +69,7 @@ const unplugin = createUnplugin<UnwasmPluginOptions>((opts) => {
  external: true,
  };
  }
- if (id.endsWith(".wasm")) {
+ if (WASM_ID_RE.test(id)) {
  const r = await this.resolve(id, importer, { skipSelf: true });
  if (r?.id && r.id !== id) {
  return {
@@ -91,23 +97,34 @@ const unplugin = createUnplugin<UnwasmPluginOptions>((opts) => {
  return getPluginUtils();
  }
 
- if (!id.endsWith(".wasm") || !existsSync(id)) {
+ if (!WASM_ID_RE.test(id)) {
+ return;
+ }
+
+ const idPath = id.split("?")[0];
+ if (!existsSync(idPath)) {
  return;
  }
 
- this.addWatchFile(id);
+ this.addWatchFile(idPath);
 
- const buff = await fs.readFile(id);
+ const buff = await fs.readFile(idPath);
  return buff.toString("binary");
  },
  async transform(code, id) {
- if (!id.endsWith(".wasm")) {
+ if (!WASM_ID_RE.test(id)) {
  return;
  }
 
  const buff = Buffer.from(code, "binary");
- const name = `wasm/${basename(id, ".wasm")}-${sha1(buff)}.wasm`;
- const parsed = parse(name, buff);
+
+ const isModule = id.endsWith("?module");
+
+ const name = `wasm/${basename(id.split("?")[0], ".wasm")}-${sha1(buff)}.wasm`;
+
+ const parsed = isModule
+ ? { imports: [], exports: ["default"] }
+ : parse(name, buff);
 
  const asset = (assets[name] = <WasmAsset>{
  name,
@@ -118,7 +135,9 @@ const unplugin = createUnplugin<UnwasmPluginOptions>((opts) => {
  });
 
  return {
- code: await getWasmBinding(asset, opts),
+ code: isModule
+ ? await getWasmModuleBinding(asset, opts)
+ : await getWasmESMBinding(asset, opts),
  map: { mappings: "" },
  };
  },
@@ -129,8 +148,8 @@ const unplugin = createUnplugin<UnwasmPluginOptions>((opts) => {
 
  if (
  !(
- chunk.moduleIds.some((id) => id.endsWith(".wasm")) ||
- chunk.imports.some((id) => id.endsWith(".wasm"))
+ chunk.moduleIds.some((id) => WASM_ID_RE.test(id)) ||
+ chunk.imports.some((id) => WASM_ID_RE.test(id))
  )
  ) {
  return;

src/plugin/runtime.ts

@@ -9,7 +9,10 @@ import {
 // https://marketplace.visualstudio.com/items?itemName=Tobermory.es6-string-html
 const js = String.raw;
 
-export async function getWasmBinding(
+/**
+ * Returns ESM compatible exports binding
+ */
+export async function getWasmESMBinding(
  asset: WasmAsset,
  opts: UnwasmPluginOptions,
 ) {
@@ -73,6 +76,26 @@ export default _mod;
  }
 }
 
+/**
+ * Returns WebAssembly.Module binding for compatibility
+ */
+export function getWasmModuleBinding(
+ asset: WasmAsset,
+ opts: UnwasmPluginOptions,
+) {
+ return opts.esmImport
+ ? js`
+const _mod = ${opts.lazy === true ? "" : `await`} import("${UNWASM_EXTERNAL_PREFIX}${asset.name}").then(r => r.default || r);
+export default _mod;
+ `
+ : js`
+import { base64ToUint8Array } from "${UMWASM_HELPERS_ID}";
+const _data = base64ToUint8Array("${asset.source.toString("base64")}");
+const _mod = new WebAssembly.Module(_data);
+export default _mod;
+ `;
+}
+
 export function getPluginUtils() {
  // --- Shared utils for the generated code ---
  return js`

test/fixture/module-import.mjs

@@ -0,0 +1,10 @@
+import _sumMod from "@fixture/wasm/sum.wasm?module";
+
+const { sum } = await WebAssembly.instantiate(_sumMod).then((i) => i.exports);
+
+export function test() {
+ if (sum(1, 2) !== 3) {
+ return "FALED: sum";
+ }
+ return "OK";
+}

test/plugin.test.ts

@@ -37,6 +37,17 @@ describe("plugin:rollup", () => {
  const resText = await _evalCloudflare(name).then((r) => r.text());
  expect(resText).toBe("OK");
  });
+
+ it("module", async () => {
+ const { output } = await _rollupBuild(
+ "fixture/module-import.mjs",
+ "rollup-module",
+ {},
+ );
+ const code = output[0].code;
+ const mod = await evalModule(code, { url: r("fixture/rollup-module.mjs") });
+ expect(mod.test()).toBe("OK");
+ });
 });
 
 // --- Utils ---