Transform WebAssembly binaries into instantly usable Node.js modules

Package WebAssembly binaries into instantly usable Node.js modules

Table of Contents

• Installation
• Usage
  • Pack Command
  • Types Command
  • Help Command
• Examples
• Output Structure
• Requirements
• Limitations
• License

Installation

npm install -g wasmx-cli

Usage

Pack Command

Package a WASM file into a Node.js module:

wasmx pack input.wasm [flags]

Available Flags

| Flag | Description | Default | |------|-------------|---------| | -o, --output <dir> | Output directory | pkg | | -e, --embed | Embed WASM as base64 if ≤512KB | External file | | -n, --name <string> | Package name (sanitized to kebab-case) | Filename stem | | -T, --no-types | Skip .d.ts generation | Generate types | | -t, --target <semver> | Minimum Node.js version | 18.0.0 | | -s, --strict | Fail on non-env imports or no exports | Lenient | | -q, --quiet | Suppress stdout, errors to stderr only | Show output | | -f, --force | Overwrite existing output directory | Abort if exists | | -M, --memory-pages <N> | Initial WebAssembly.Memory pages | 256 (clamped 1-65536) | | -c, --change-version <ver> | Set package.json version | 1.0.0 |

Types Command

Generate TypeScript type definitions from WASM exports:

wasmx types input.wasm -o types.d.ts
wasmx types input.wasm -o types.d.ts -m mymodule

Help Command

Show help for the pack command:

wasmx pack-help
# or alias:
wasmx ph

Examples

Basic Packaging

Package WASM with embedded binary:

wasmx pack add.wasm -o pkg -e -n add-wasm

Strict Validation

Package with strict validation (rejects non-env imports):

wasmx pack add.wasm -o pkg --strict --force

Type Generation

Generate standalone type definitions:

wasmx types add.wasm -o types.d.ts

Wrap types in declare module block:

wasmx types add.wasm -o types.d.ts -m add-wasm

Output Structure

Running wasmx pack add.wasm -o pkg -e produces:

pkg/
├── index.js        # CommonJS loader
├── index.mjs       # ESM loader
├── index.d.ts      # TypeScript definitions
├── package.json    # npm metadata
└── module.wasm     # only if not embedded

Both loaders provide runtime WebAssembly.Memory allocation, automatic export name sanitization (e.g. foo-bar becomes _wasm_foo_bar), and zero external dependencies.

Requirements

• ✅ Node.js 16.0.0 or higher
• ✅ WASM files should use only env imports (use --strict to validate at pack time)
• ✅ For global installs on Windows: executable must have no file extension (wasmx not wasmx.js) to avoid VS Code hijacking

Limitations

• ⚠️ TypeScript definitions use generic signatures (...args: number[]) => number instead of precise parameter types
• ⚠️ Custom imports beyond env.memory require manual loader modification
• ⚠️ WASM files with non-env imports will fail at runtime unless the host environment provides those imports

License

This project is licensed under the MIT License.

Made with ❤️ for the WebAssembly community