unwasm

library0.5.3jsnpmunverified

unwasm provides a suite of universal WebAssembly (Wasm) tools for JavaScript, designed to simplify the integration of `.wasm` modules across various JavaScript runtimes, frameworks, and build environments. It currently stands at version 0.5.3, with a release cadence that includes frequent patch and minor updates. The project's core mission is to align with the WebAssembly/ES Module Integration proposal while maintaining broad compatibility with existing ecosystem libraries. Its key differentiators include automated resolution of WebAssembly imports, dynamic generation of code bindings tailored for bundlers, and a flexible API supporting both static and dynamic `.wasm` module imports. This includes explicit support for import objects and direct `WebAssembly.Module` instances via a `?module` suffix, catering to environments both with and without top-level `await` capabilities.

serialization web-framework

npm install unwasm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UNWASM

unwasm

serializationjavascriptv0.5.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sum

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

✗ const { sum } = require('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

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

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

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

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

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

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

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();

unwasm --version

Debug

Known issues

breakingunwasm 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.

affects: >=0.4.0

gotchaWhen 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.

affects: >=0.1.0

breakingThe 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.

affects: >=0.5.0

Errors

Common errors & fixes

TypeError: require is not a function in ES module scope

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')

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.

Upgrade

Version history

0.5.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/unjs/unwasm ↗

packagehttps://www.npmjs.com/package/unwasm ↗

homepagehttps://unwasm.dev ↗