unwasm

unwasm

Universal WebAssembly tools for JavaScript.

Goal

This project aims to make a common and future-proof solution for WebAssembly modules support suitable for various JavaScript runtimes, frameworks, and build Tools following WebAssembly/ES Module Integration proposal from WebAssembly Community Group as much as possible while also trying to keep compatibility with current ecosystem libraries.

Roadmap

The development will be split into multiple stages.

[!IMPORTANT] This Project is under development! See the linked discussions to be involved!

• Universal builder plugins built with unjs/unplugin (unjs/unwasm#2)
  • Rollup
• Tools to operate and inspect .wasm files (unjs/unwasm#3)
• Runtime utils (unjs/unwasm#4)
• ESM loader for Node.js and other JavaScript runtimes (unjs/unwasm#5)
• Integration with Wasmer (unjs/unwasm#6)
• Convention and tools for library authors exporting wasm modules (unjs/unwasm#7)

Bindings API

When importing a .wasm module using unwasm, it will take steps to transform the binary and finally resolve to an ESM module that allows you to interact with the WASM module. The returned result is a Proxy object. This proxy allows to use of an elegant API while also having both backward and forward compatibility with WASM modules as the ecosystem evolves.

WebAssembly modules that don't require any imports, can be imported simply like you import any other ESM module.

Using static import:

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

Using dynamic import:

const { sum } = await import("unwasm/examples/sum.wasm").then(
  (mod) => mod.default,
);

In case your WebAssembly module requires an import object (which is likely!), the usage syntax would be slightly different as we need to initate the module with an import object first.

Using static import with imports object:

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

await $init({
  env: {
    seed: () => () => Math.random() * Date.now(),
  },
});

Using dynamic import with imports object:

const { rand } = await import("unwasm/examples/rand.wasm").then((mod) =>
  mod.$init({
    env: {
      seed: () => () => Math.random() * Date.now(),
    },
  }),
);

[!NOTE] When using static import syntax, and before calling $init, the named exports will be wrapped into a function by proxy that waits for the module initialization and before that, if called, will immediately try to call $init() and return a Promise that calls a function after init.

[!NOTE] Named exports with the $ prefix are reserved for unwasm. In case your module uses them, you can access them from the $exports property.

Usage

Unwasm needs to transform the .wasm imports to the compatible bindings. Currently only method is using a rollup plugin. In the future, more usage methods will be introduced.

Install

First, install the unwasm npm package:

# npm
npm install --dev unwasm

# yarn
yarn add -D unwasm

# pnpm
pnpm i -D unwasm

# bun
bun i -D unwasm

Builder Plugins

Rollup

// rollup.config.js
import unwasmPlugin from "unwasm/plugin";

export default {
  plugins: [
    unwasmPlugin.rollup({
      /* options */
    }),
  ],
};

Plugin Options

• esmImport: Direct import the wasm file instead of bundling, required in Cloudflare Workers (default is false)
• lazy: Import .wasm files using a lazily evaluated promise for compatibility with runtimes without top-level await support (default is false)

Development

• Clone this repository
• Install the latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev
• Optionally install es6-string-html extension to make it easier to work with string templates.

License

Made with 💛

Published under MIT License.

Changelog

v0.2.0

compare changes

🚀 Enhancements

• ⚠️ Support custom init (6861425)
• Expose unwasm/examples (04127bf)

💅 Refactors

• Readable code and esm tests against miniflare (d03a1cb)

🏡 Chore

• release: V0.1.0 (4912c48)
• Update readme (fea5f27)
• Eslint ignore $init import (9673e5c)
• Update readme (e1e49a1)
• Update readme (77f9f4f)

⚠️ Breaking Changes

• ⚠️ Support custom init (6861425)

❤️ Contributors

• Pooya Parsa (@pi0)