Binaryen.js

129.0.0 verified Fri May 01 auth: no javascript

Binaryen.js provides prebuilt browser and Node.js binaries of Binaryen, a compiler infrastructure and toolchain library for WebAssembly. Version 129.0.0 is the latest stable release; the project follows Binaryen releases closely. It optimizes Wasm modules, performs transformations (e.g., inlining, dead code elimination), and validates/parses Wasm. Key differentiators: it works entirely in JavaScript with no native dependencies, making it suitable for web build pipelines, and it supports both ESM and CommonJS. Compared to wasm-opt CLI, it enables programmatic Wasm optimization in Node.js or browser bundlers.

Common errors

error TypeError: Binaryen.Module is not a constructor ↓

cause Forgetting to await Binaryen.ready() before using Binaryen.Module.

fix

Add 'await Binaryen.ready();' before any other Binaryen calls.

error Error: Binaryen is not initialized ↓

cause Binaryen.ready() not called or not awaited.

fix

Ensure Binaryen.ready() is called and awaited at the start of your async function.

error require() of ES Module ... not supported ↓

cause Using CommonJS require() on an ESM-only package (version >=100).

fix

Switch to 'import Binaryen from 'binaryen'' and use an ESM-compatible setup.

error Module "..." has been added to an invalid position ↓

cause Incorrect order of module construction (e.g., adding function export before function).

fix

Ensure all function types, functions, and imports are added before exports.

Warnings

gotcha Binaryen.ready() must be called and awaited before any other API calls; failure leads to 'Binaryen is not initialized' errors. ↓

fix Always await Binaryen.ready() at top of your script.

gotcha The Binaryen npm package is ESM-only starting from version 100.0.0; CommonJS require() will fail. ↓

fix Use import syntax or upgrade to Node >=12.22 or use dynamic import().

gotcha The API is synchronous but built on WebAssembly; thread-blocking operations may impact performance on the main thread. ↓

fix Consider offloading to a Web Worker or use Async variants if available (currently no async API, but Binaryen.ready is async).

gotcha TypeScript types are provided but may lag behind the Native API; some methods may be missing or incorrectly typed. ↓

fix Check the type definition file (.d.ts) for completeness; use 'as any' if needed.

Install

npm install binaryen

yarn add binaryen

pnpm add binaryen

Imports

Binaryen
```
import Binaryen from 'binaryen'
```
Default export in ESM is a namespace object; call Binaryen.ready() before use (Async).

Module

import Binaryen from 'binaryen'; const mod = new Binaryen.Module()

Module is a class on the default export; not a named export.

readBinary (via Binaryen)

import Binaryen from 'binaryen'; const wasmBuffer = Binaryen.readBinary(new Uint8Array([...]))

readBinary is attached to the default export, not imported standalone.

Quickstart

Creates a simple Wasm module with an 'add' function, validates, and emits binary.

import Binaryen from 'binaryen';

async function main() {
  await Binaryen.ready(); // ensure runtime is initialized
  const module = new Binaryen.Module();
  const funcType = module.addFunctionType('i32', Binaryen.i32, []);
  const func = module.addFunction('add', funcType, [], [
    module.local.get(0, Binaryen.i32),
    module.local.get(1, Binaryen.i32),
    module.i32.add()
  ]);
  module.addFunctionExport('add', 'add');
  module.validate();
  const binary = module.emitBinary();
  console.log('Wasm binary size:', binary.length, 'bytes');
}
main();