unwasm

unwasm can automatically resolve a .wasm module's imports using import maps. You can define these mappings in a parent package.json using the imports field.

For example, if a .wasm file requires an env module, you can map it like this:

{
  "exports": {
    "./rand.wasm": "./rand.wasm"
  },
  "imports": {
    "env": "./env.mjs"
  }
}

You can also use the # prefix (e.g., #env) to follow Node.js import map conventions.

To use unwasm with Rollup, install the package and add the unwasm plugin to your rollup.config.js.

// rollup.config.js
import { unwasm } from "unwasm/plugin";

export default {
  plugins: [unwasm({/* options */})],
};

Install the unwasm package using your preferred package manager. The following command uses nypm to auto-detect your package manager:

npx nypm install unwasm

The plugin handles .wasm imports by transforming them into JavaScript code. You can control the behavior using query parameters or plugin options:

1. Module Mode: By default, the plugin attempts to parse the WASM module to determine its imports and exports. If parsing fails, it falls back to a generic module mode.
2. Explicit Module Mode: Appending ?module to the import path (e.g., import wasm from './file.wasm?module') forces the plugin to treat the file as a module.
3. ESM Bindings: If esmImport: true is set in the plugin configuration, the plugin generates ESM bindings that reference the WASM files as external assets.

The unwasm plugin accepts the following configuration options:

• esmImport (default: false): If true, the .wasm file is imported directly instead of being bundled. This is required for environments like Cloudflare Workers that support native .wasm module imports.
• lazy (default: false): If true, .wasm files are imported through a lazily evaluated proxy. This is useful for runtimes that do not support top-level await.

If a library requires a WebAssembly.Module instance instead of an instantiated object, append the ?module suffix to your import. This allows you to manually instantiate the module using WebAssembly.instantiate.

import _sumMod from "sum.wasm?module";
const { sum } = await WebAssembly.instantiate(_sumMod).then((i) => i.exports);

The parseWasm tool is a dependency-free helper that parses a WebAssembly binary to extract its interface (imports and exports) without decoding the entire module. This is useful for build-time analysis.

import { readFile } from "node:fs/promises";
import { parseWasm } from "unwasm/tools";

const source = await readFile(new URL("examples/sum.wasm", import.meta.url));
const parsed = parseWasm(source);
console.log(JSON.stringify(parsed, undefined, 2));

When using the Unwasm plugin, you can provide an options object to control how WebAssembly assets are handled.

Key options include:

• esmImport: If set to true, the plugin will directly import .wasm files instead of bundling them as base64 strings. Defaults to false.
• lazy: If set to true, the plugin avoids using top-level await and instead uses a proxy. This is useful for compatibility with environments that do not support top-level await. Defaults to false.
• silent: If set to true, all warnings from the plugin are suppressed. Defaults to false.

const options: UnwasmPluginOptions = {
  esmImport: true,
  lazy: true,
  silent: false
};

The unwasm build configuration uses defineBuildConfig to specify the entry points for the project. Currently, the build targets two main entry points: src/plugin/index and src/tools/index.

import { defineBuildConfig } from "obuild/config";

export default defineBuildConfig({
  entries: ["src/plugin/index", "src/tools/index"],
});

The parseWasm function returns an object describing the module's interface. The structure is as follows:

{
  "modules": [
    {
      "exports": [
        {
          "id": number,
          "name": string,
          "type": "Func" | "Memory" | ...
        }
      ],
      "imports": [
        {
          "module": string,
          "name": string,
          "params": array,
          "returnType": string
        }
      ]
    }
  ]
}