{"id":12321,"library":"unwasm","title":"unwasm: Universal WebAssembly Tools","description":"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.","status":"active","version":"0.5.3","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/unwasm","tags":["javascript"],"install":[{"cmd":"npm install unwasm","lang":"bash","label":"npm"},{"cmd":"yarn add unwasm","lang":"bash","label":"yarn"},{"cmd":"pnpm add unwasm","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"unwasm is ESM-only since v0.4.0. Direct CommonJS imports of WASM modules processed by unwasm are not supported.","wrong":"const { sum } = require('unwasm/examples/sum.wasm');","symbol":"sum","correct":"import { sum } from 'unwasm/examples/sum.wasm';"},{"note":"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.","wrong":"import { rand } from 'unwasm/examples/rand.wasm';\nconst randomNumber = rand();","symbol":"initRand, rand","correct":"import initRand, { rand } from 'unwasm/examples/rand.wasm';\n// ... await initRand({ env: { seed: () => () => Math.random() * Date.now() } });"},{"note":"The '?module' suffix imports the raw WebAssembly.Module instance as a default export, allowing manual instantiation.","wrong":"import { _sumMod } from 'unwasm/examples/sum.wasm?module';","symbol":"_sumMod","correct":"import _sumMod from 'unwasm/examples/sum.wasm?module';"}],"quickstart":{"code":"import initRand, { rand } from \"unwasm/examples/rand.wasm\";\n\n// This quickstart assumes unwasm's build-time integration is configured\n// to process '.wasm' imports, e.g., through a Vite or Rollup plugin.\n\nasync function runWasmExample() {\n  // Initialize the WebAssembly module that requires an import object.\n  // This example provides a 'seed' function for the 'env' namespace.\n  await initRand({\n    env: {\n      seed: () => () => Math.random() * Date.now()\n    }\n  });\n\n  // Now the 'rand' function (exported from rand.wasm) can be called.\n  const randomNumber = rand();\n  console.log(\"Generated random number from WASM module:\", randomNumber);\n\n  // Demonstrate dynamic import for a simpler module without explicit initialization.\n  const { sum } = await import(\"unwasm/examples/sum.wasm\");\n  const result = sum(10, 20);\n  console.log(\"Result of sum(10, 20) from WASM module:\", result);\n}\n\nrunWasmExample();","lang":"javascript","description":"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."},"warnings":[{"fix":"Refactor your codebase to use ES Modules (import/export syntax) for unwasm and any imported .wasm files.","message":"unwasm transitioned to an ESM-only distribution. CommonJS (require()) syntax for importing unwasm or any .wasm files processed by unwasm is no longer supported.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Switch to ES module `import` syntax. For example, `import { Name } from 'pkg'` instead of `const Name = require('pkg');`","cause":"Attempting to use CommonJS `require()` to import `unwasm` or `.wasm` files after v0.4.0, which transitioned to an ESM-only distribution.","error":"TypeError: require is not a function in ES module scope"},{"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.","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.","error":"TypeError: rand is not a function / Cannot read properties of undefined (reading 'call')"}],"ecosystem":"npm"}