unwasm: Universal WebAssembly Tools

Common errors

• TypeError: require is not a function in ES module scope

  cause Attempting to use CommonJS `require()` to import `unwasm` or `.wasm` files after v0.4.0, which transitioned to an ESM-only distribution.
  fix Switch to ES module `import` syntax. For example, `import { Name } from 'pkg'` instead of `const Name = require('pkg');`

• TypeError: rand is not a function / Cannot read properties of undefined (reading 'call')

  cause Calling a named WebAssembly export (e.g., `rand`) from a statically imported module before its required 'init' function has been called and awaited with the necessary import object.
  fix Ensure the default 'init' function (e.g., `initRand`) for the `.wasm` module is called and awaited with its import object before attempting to use any of its named exports.

Warnings

• breaking unwasm transitioned to an ESM-only distribution. CommonJS (require()) syntax for importing unwasm or any .wasm files processed by unwasm is no longer supported.
  Fix: Refactor your codebase to use ES Modules (import/export syntax) for unwasm and any imported .wasm files.
• gotcha When using static imports for WebAssembly modules that require an import object, named exports will be proxied. They will only become callable after the default 'init' function (e.g., `initRand`) has been called and awaited with the necessary import object.
  Fix: Always call and await the default 'init' function (e.g., `initRand`) with the required import object before attempting to call any named exports from the `.wasm` module.
• breaking The behavior for WebAssembly module instantiation changed with the introduction of 'auto fallback to module mode'. This might alter how some environments or existing configurations handle module instantiation if they previously relied on specific manual handling of different modes.
  Fix: Review your application's WebAssembly instantiation logic, especially in environments where specific module mode handling was previously implemented. Ensure compatibility with the new automatic fallback behavior.

Install

• npm install unwasm npm
• yarn add unwasm yarn
• pnpm add unwasm pnpm

Imports

• sum
  wrong:

  const { sum } = require('unwasm/examples/sum.wasm');

  correct:

  import { sum } from 'unwasm/examples/sum.wasm';

  unwasm is ESM-only since v0.4.0. Direct CommonJS imports of WASM modules processed by unwasm are not supported.
• initRand, rand
  wrong:

  import { rand } from 'unwasm/examples/rand.wasm';
  const randomNumber = rand();

  correct:

  import initRand, { rand } from 'unwasm/examples/rand.wasm';
  // ... await initRand({ env: { seed: () => () => Math.random() * Date.now() } });

  For statically imported WASM modules requiring an import object, the default 'init' function (e.g., initRand) must be called and awaited before named exports become usable.
• _sumMod
  wrong:

  import { _sumMod } from 'unwasm/examples/sum.wasm?module';

  correct:

  import _sumMod from 'unwasm/examples/sum.wasm?module';

  The '?module' suffix imports the raw WebAssembly.Module instance as a default export, allowing manual instantiation.

Quickstart

This quickstart demonstrates the JavaScript API for interacting with WebAssembly modules after they have been processed by unwasm's build-time integration. It showcases both static and dynamic imports, including initialization with an import object, and the subsequent calling of exported WebAssembly functions.

import initRand, { rand } from "unwasm/examples/rand.wasm";

// This quickstart assumes unwasm's build-time integration is configured
// to process '.wasm' imports, e.g., through a Vite or Rollup plugin.

async function runWasmExample() {
  // Initialize the WebAssembly module that requires an import object.
  // This example provides a 'seed' function for the 'env' namespace.
  await initRand({
    env: {
      seed: () => () => Math.random() * Date.now()
    }
  });

  // Now the 'rand' function (exported from rand.wasm) can be called.
  const randomNumber = rand();
  console.log("Generated random number from WASM module:", randomNumber);

  // Demonstrate dynamic import for a simpler module without explicit initialization.
  const { sum } = await import("unwasm/examples/sum.wasm");
  const result = sum(10, 20);
  console.log("Result of sum(10, 20) from WASM module:", result);
}

runWasmExample();