WebAssembly & ESM

Today, loading WebAssembly in an ES Module project uses the WebAssembly API. The recommended approach is instantiateStreaming(), which compiles and instantiates in a single step while streaming the binary:

// math.js - ESM wrapper for a WASM module
const wasmModule = await WebAssembly.instantiateStreaming(
  fetch('./math.wasm')
);

// Export WASM functions as ESM exports
export const add = wasmModule.instance.exports.add;
export const multiply = wasmModule.instance.exports.multiply;

For more control, you can separate the compile and instantiate steps. This is useful when you need to pass imports to the WASM module or instantiate the same module multiple times:

// Advanced: fetch, compile, then instantiate with imports
const response = await fetch('./graphics.wasm');
const bytes = await response.arrayBuffer();
const compiled = await WebAssembly.compile(bytes);

// Pass JavaScript functions into WASM
const instance = await WebAssembly.instantiate(compiled, {
  env: {
    log: (value) => console.log('WASM says:', value),
    memory: new WebAssembly.Memory({ initial: 256 })
  }
});

export const render = instance.exports.render;
export const resize = instance.exports.resize;

Using WASM functions from an ESM consumer is seamless once wrapped:

// app.js - consuming the WASM-backed ESM module
import { add, multiply } from './math.js';

console.log(add(40, 2));       // 42
console.log(multiply(6, 7));   // 42

// The consumer does not know or care that
// the implementation uses WebAssembly

Source Phase Imports (TC39 Stage 3) introduce a new import source syntax that gives you a compiled WebAssembly.Module directly, without needing fetch or compile calls:

// Source phase import - returns a WebAssembly.Module
import source mathModule from './math.wasm';

// The module is already compiled, just instantiate it
const instance = await WebAssembly.instantiate(mathModule, {
  // Optional imports object
});

export const add = instance.exports.add;
export const multiply = instance.exports.multiply;

This dramatically simplifies WASM loading compared to the fetch + compile pattern. The runtime handles fetching, streaming compilation, and caching automatically:

// Before: manual fetch and compile
const response = await fetch('./math.wasm');
const bytes = await response.arrayBuffer();
const module = await WebAssembly.compile(bytes);
const instance = await WebAssembly.instantiate(module);

// After: source phase import handles it all
import source mathModule from './math.wasm';
const instance = await WebAssembly.instantiate(mathModule);

Source phase imports also enable sharing a compiled module across multiple instantiations, which is useful for worker-based parallelism:

// Share one compiled module across multiple workers
import source imageProcessor from './image-processor.wasm';

// Each worker gets its own instance with separate memory
const worker1 = await WebAssembly.instantiate(imageProcessor, {
  env: { memory: new WebAssembly.Memory({ initial: 256 }) }
});

const worker2 = await WebAssembly.instantiate(imageProcessor, {
  env: { memory: new WebAssembly.Memory({ initial: 256 }) }
});

wasm-pack (Rust to WASM)

wasm-pack compiles Rust code to WebAssembly and generates ESM-compatible JavaScript bindings automatically. It is the most mature WASM toolchain:

// src/lib.rs - Rust source
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn fibonacci(n: u32) -> u32 {
    match n {
        0 => 0,
        1 => 1,
        _ => fibonacci(n - 1) + fibonacci(n - 2),
    }
}

# Build with ESM output target
wasm-pack build --target web

# Generated output:
# pkg/
#   my_crate.js        <-- ESM wrapper (auto-generated)
#   my_crate_bg.wasm   <-- Compiled WASM binary
#   my_crate.d.ts      <-- TypeScript declarations

// Import the generated ESM wrapper
import init, { fibonacci } from './pkg/my_crate.js';

// Initialize the WASM module (required once)
await init();

console.log(fibonacci(10)); // 55

AssemblyScript (TypeScript-like to WASM)

AssemblyScript uses a TypeScript-like syntax that compiles directly to WebAssembly. It is the easiest entry point for JavaScript developers:

// assembly/index.ts - AssemblyScript source
export function add(a: i32, b: i32): i32 {
  return a + b;
}

export function isPrime(n: i32): bool {
  if (n < 2) return false;
  for (let i: i32 = 2; i * i <= n; i++) {
    if (n % i === 0) return false;
  }
  return true;
}

# Compile with ESM bindings
npx asc assembly/index.ts --outFile build/math.wasm \
  --bindings esm --optimize

// Import the generated ESM bindings
import { add, isPrime } from './build/math.js';

console.log(add(2, 3));      // 5
console.log(isPrime(17));     // true

Emscripten (C/C++ to WASM)

Emscripten compiles C and C++ code to WebAssembly with full standard library support. Use -sEXPORT_ES6=1 to generate ESM output:

// math.c - C source
#include <emscripten.h>

EMSCRIPTEN_KEEPALIVE
int factorial(int n) {
    if (n <= 1) return 1;
    return n * factorial(n - 1);
}

# Compile with ESM output
emcc math.c -o math.js \
  -sEXPORT_ES6=1 \
  -sMODULARIZE=1 \
  -sEXPORTED_FUNCTIONS='["_factorial"]' \
  -sEXPORTED_RUNTIME_METHODS='["ccall","cwrap"]'

// Import the ESM module generated by Emscripten
import createModule from './math.js';

const Module = await createModule();
const factorial = Module.cwrap('factorial', 'number', ['number']);

console.log(factorial(10)); // 3628800

WebAssembly excels where JavaScript hits performance limits. Combined with ES Modules, you get a clean integration boundary between high-performance WASM code and your JavaScript application:

A common pattern is to use WASM for the hot path and JavaScript for everything else:

// image-editor.js - WASM for heavy lifting, JS for UI
import { applyFilter, resize } from './image-wasm.js';

export async function processImage(imageData, options) {
  // JavaScript handles UI logic and validation
  if (!imageData || imageData.length === 0) {
    throw new Error('No image data provided');
  }

  // WASM handles the performance-critical work
  const filtered = applyFilter(imageData, options.filter);
  const resized = resize(filtered, options.width, options.height);

  // JavaScript handles the result
  return new Blob([resized], { type: 'image/png' });
}