🔌 Using WASM in Web Apps

Loading a Module

Before you can call anything, the browser must fetch the .wasm bytes, compile them to machine code, and instantiate the module (allocate its memory and wire up imports). The modern one-liner that does all three efficiently is WebAssembly.instantiateStreaming.

// Fetch, compile, and instantiate — all while the file is still
// downloading. This is the recommended path.
const { instance, module } = await WebAssembly.instantiateStreaming(
  fetch('math.wasm'),
  importObject   // optional — functions/values we give TO the module
);

// Everything the module exported lives here:
const { add, fibonacci } = instance.exports;
console.log(add(5, 3));       // 8
console.log(fibonacci(10));   // 55

The fallback: fetch then instantiate

If you can't control the MIME type (or you already have the bytes in hand), compile from an ArrayBuffer:

async function loadModule(url, importObject) {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Failed to fetch ${url}: ${response.status}`);
  }
  const bytes = await response.arrayBuffer();
  // Compile + instantiate from the raw bytes.
  return WebAssembly.instantiate(bytes, importObject);
}

const { instance } = await loadModule('math.wasm', {});
console.log(instance.exports.add(40, 2)); // 42

Calling Functions Both Ways

Interop flows in two directions. JavaScript calls into WASM through instance.exports, and WASM calls back out through the functions you supply in the import object.

JS calls WASM

Exported functions behave like ordinary JavaScript functions. You can store them in variables, pass them as callbacks, and wire them to event listeners:

const { multiply } = instance.exports;

document.getElementById('calculate').addEventListener('click', () => {
  const a = Number(document.getElementById('valueA').value);
  const b = Number(document.getElementById('valueB').value);
  // Runs compiled code, returns a plain JS number.
  document.getElementById('result').textContent = multiply(a, b);
});

WASM calls JS via imports

Since WebAssembly has no DOM or console of its own, you hand it JavaScript functions to call. Those live under a namespace (commonly env) in the import object:

const importObject = {
  env: {
    // A function the module can call to report progress.
    onProgress: (percent) => {
      console.log(`Working: ${percent}%`);
    },
    // You can also supply memory and other values here.
    memory: new WebAssembly.Memory({ initial: 10 })
  }
};

const { instance } = await WebAssembly.instantiateStreaming(
  fetch('worker.wasm'),
  importObject
);
instance.exports.run(); // internally calls back into onProgress

The Interop Boundary

Every call between JavaScript and WebAssembly crosses a boundary, and what you can carry across it depends on the data's type. This single fact shapes almost every design decision you'll make.

The four native types

WebAssembly's core knows exactly four value types, all numeric:

These pass directly and cheaply. Anything else — a string, an array, an object — has no native representation across the boundary. To move it, you serialize it into the shared linear memory and pass a pointer (just an i32 offset) instead.

Working with Linear Memory

A module's linear memory is a resizable ArrayBuffer. JavaScript reaches into it by creating a typed-array view over memory.buffer. No copying is involved to view it — you're looking at the very same bytes the module sees.

// Create a memory: 2 pages now (each page is 64 KiB), up to 10.
const memory = new WebAssembly.Memory({ initial: 2, maximum: 10 });

// Different views interpret the same bytes differently:
const bytes = new Uint8Array(memory.buffer);   // one byte at a time
const ints  = new Int32Array(memory.buffer);   // four bytes at a time

bytes[0] = 255;
console.log(bytes[0]); // 255

// Grow by 2 more pages when you need room:
const oldPageCount = memory.grow(2); // returns the previous page count
console.log(`Grew from ${oldPageCount} pages`);

memory.grow(2);
// The old `bytes` is now stale — make a fresh view:
const freshBytes = new Uint8Array(memory.buffer);

Allocating space inside the module

You don't scribble anywhere in memory — you ask the module for a free region. Most toolchains export a malloc/free pair (or generate them for you). The pattern is allocate → write → call → read → free:

const { malloc, free, sumBytes, memory } = instance.exports;

// 1. Ask WASM for 4 bytes of space; get back a pointer (offset).
const ptr = malloc(4);

// 2. Write into that region through a view.
const view = new Uint8Array(memory.buffer, ptr, 4);
view.set([10, 20, 30, 40]);

// 3. Call the compiled function, passing the pointer + length.
console.log(sumBytes(ptr, 4)); // 100

// 4. Always release what you allocated.
free(ptr);

Marshalling Strings

Strings are the classic "why is this hard?" case. JavaScript strings are UTF-16; C strings are UTF-8 bytes terminated by a zero. To hand a string to WASM you must encode it into memory; to read one back you must decode the bytes. The TextEncoder and TextDecoder APIs do the heavy lifting.

// --- JS -> WASM: write a string into linear memory ---
function passString(instance, str) {
  const { malloc, memory } = instance.exports;
  const encoder = new TextEncoder();
  const bytes = encoder.encode(str + '\0'); // null-terminated

  const ptr = malloc(bytes.length);
  new Uint8Array(memory.buffer).set(bytes, ptr);
  return ptr; // hand this pointer to a WASM function
}

// --- WASM -> JS: read a null-terminated string back out ---
function readString(instance, ptr) {
  const { memory } = instance.exports;
  const bytes = new Uint8Array(memory.buffer);
  let end = ptr;
  while (bytes[end] !== 0) end++;        // find the terminator
  return new TextDecoder().decode(bytes.subarray(ptr, end));
}

// Usage: length of a string, computed inside WASM
const ptr = passString(instance, 'Hello, WebAssembly!');
console.log(instance.exports.stringLength(ptr)); // 19
instance.exports.free(ptr);

Case Study: Image Filter

Image processing is the poster child for WebAssembly: millions of pixels, simple arithmetic per pixel, and a big buffer of numbers that lives in memory. Here's the full round trip — canvas pixels into WASM, filtered, and back onto the canvas.

The C filter (compiled to WASM)

// grayscale.c — compiled with Emscripten to grayscale.wasm
#include <emscripten.h>
#include <stdint.h>

// Convert an RGBA pixel buffer to grayscale, in place.
EMSCRIPTEN_KEEPALIVE
void applyGrayscale(uint8_t* data, int pixelCount) {
    for (int i = 0; i < pixelCount; i++) {
        uint8_t* p = data + i * 4;               // RGBA = 4 bytes
        uint8_t gray = (uint8_t)(0.299 * p[0] +  // luminance formula
                                 0.587 * p[1] +
                                 0.114 * p[2]);
        p[0] = gray;  // R
        p[1] = gray;  // G
        p[2] = gray;  // B
        // p[3] (alpha) is left unchanged
    }
}

The JavaScript driver

class ImageProcessor {
  async init(url) {
    const { instance } = await WebAssembly.instantiateStreaming(fetch(url), {});
    this.exports = instance.exports;
    return this;
  }

  grayscale(canvas) {
    const ctx = canvas.getContext('2d');
    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    const pixels = imageData.data;            // Uint8ClampedArray, RGBA
    const { malloc, free, applyGrayscale, memory } = this.exports;

    // 1. Reserve space in WASM memory and copy the pixels in (ONE crossing).
    const ptr = malloc(pixels.length);
    new Uint8Array(memory.buffer).set(pixels, ptr);

    // 2. Do all the per-pixel work inside WASM in a single call.
    applyGrayscale(ptr, canvas.width * canvas.height);

    // 3. Copy the processed bytes back and repaint.
    const result = new Uint8Array(memory.buffer, ptr, pixels.length);
    pixels.set(result);
    ctx.putImageData(imageData, 0, 0);

    // 4. Release the buffer.
    free(ptr);
  }
}

const processor = await new ImageProcessor().init('grayscale.wasm');
processor.grayscale(document.getElementById('photo'));

Integrating with a Framework

In a component-based app, the trick is to load the module once and handle the async lifecycle cleanly. Here's a compact React example that loads on mount and recomputes when its input changes:

import { useState, useEffect } from 'react';

function FibCalculator() {
  const [wasm, setWasm] = useState(null);
  const [n, setN] = useState(10);
  const [result, setResult] = useState(null);

  // Load the module a single time when the component mounts.
  useEffect(() => {
    let cancelled = false;
    WebAssembly.instantiateStreaming(fetch('/math.wasm'), {})
      .then(({ instance }) => {
        if (!cancelled) setWasm(instance);
      })
      .catch((err) => console.error('WASM load failed:', err));
    return () => { cancelled = true; };
  }, []);

  // Recompute whenever the module is ready or the input changes.
  useEffect(() => {
    if (wasm) setResult(wasm.exports.fibonacci(Number(n)));
  }, [wasm, n]);

  return (
    <div>
      <input
        type="number"
        value={n}
        onChange={(e) => setN(e.target.value)}
      />
      <p>Result: {result ?? 'Loading…'}</p>
    </div>
  );
}

Practice & Quiz

function sumViaWasm(instance, arr) {
  // TODO: allocate, copy in as Int32, call sumInts once, free, return
}
console.log(sumViaWasm(instance, [10, 20, 30])); // 60

function sumViaWasm(instance, arr) {
  const { malloc, free, sumInts, memory } = instance.exports;
  const ptr = malloc(arr.length * 4);            // 4 bytes per i32
  const view = new Int32Array(memory.buffer, ptr, arr.length);
  view.set(arr);                                 // copy in — one crossing
  const total = sumInts(ptr, arr.length);        // one WASM call
  free(ptr);
  return total;
}

const view = new Uint8Array(instance.exports.memory.buffer);
instance.exports.loadBigAsset();   // may call memory.grow() internally
view[0] = 42;                      // 💥 sometimes throws

instance.exports.loadBigAsset(); // may grow memory
const view = new Uint8Array(instance.exports.memory.buffer); // fresh
view[0] = 42; // safe

Best Practices & Pitfalls

✅ Do

• Prefer instantiateStreaming and serve .wasm as application/wasm
• Load a module once and cache the instance; reuse it across calls
• Batch work: copy bulk data into memory and process it in a single WASM call
• Follow allocate → write → call → read → free and always release what you malloc
• Recreate typed-array views after any memory.grow()
• Let wasm-bindgen or Emscripten generate marshalling glue for real projects

❌ Don't

• Call a WASM function once per element in a hot loop — the boundary overhead piles up
• Hold onto a typed-array view across code that might grow memory
• Forget to free — WASM linear memory has no garbage collector for your allocations
• Assume i64 exports return a number — they return BigInt
• Block first paint on a large module — load it lazily when the feature is actually used

Summary

📚 Additional Resources

• MDN — Loading and running WebAssembly code
• MDN — Using the WebAssembly JavaScript API
• The wasm-bindgen Guide
• WebAssembly.org — Developer's Guide

🚀 What's Next?

You can now wire WASM into an app — but should you, and how do you make it fast? The next lesson, Performance Considerations, measures WASM against JavaScript, shows where it wins and loses, and covers optimization from source flags to SIMD and batching.