JavaScript & WebAssembly

What WebAssembly is

WebAssembly, often called Wasm, is a compact binary instruction format that browsers and other runtimes can execute. It is normally produced by a compiler from another language, then loaded and called by JavaScript. It is a teammate for JavaScript, not a new way to write every web page.

Use it when a small part of an app spends a lot of time doing predictable numeric work: resizing an image, decoding video, processing audio, running a game loop, or calculating a large model. Keep page layout, buttons, forms, network requests, and most application logic in JavaScript where browser APIs are designed to be used.

A browser treats a Wasm module as a small, typed virtual machine program inside its JavaScript engine. The module can only use the imports and memory it was given, and the engine validates its structure before it runs. That makes it portable across machines while still letting the engine compile its instructions into fast local machine code.

Do not reach for Wasm because a task merely sounds technical. First profile the real page. A short DOM update, a network wait, or a database request is often the bottleneck; a compact repeated calculation is the more promising candidate.

The next lesson is not published yet. This is the last lesson in this stage, so the trail pauses here rather than guessing at a link. The earlier typed arrays lesson is useful preparation because typed arrays also expose bytes with clear numeric types.

A tiny Wasm module

The smallest useful way to meet Wasm is a function that adds two integers. The bytes below are a complete module. They start with the magic header \0asm, then contain a version, a function type, one function, an export named add, and the instructions that read two values and add them.

1const bytes = new Uint8Array([0,97,115,109,1,0,0,0,1,7,1,96,2,127,127,1,127,3,2,1,0,7,7,1,3,97,100,100,0,0,10,9,1,7,0,32,0,32,1,106,11]);2const { instance } = await WebAssembly.instantiate(bytes);3console.log(instance.exports.add(2, 3));

Line 1 creates a Uint8Array holding the module bytes. Line 2 asks the WebAssembly API to validate, compile, and instantiate those bytes. Line 3 calls the exported add function. The real output is 5.

The first eight bytes are the \0asm header and version. The next sections say what function shape exists, which function uses that shape, which public name exposes it, and which instructions implement it. A section has an ID byte, a byte length, then its payload, so the engine can skip a section it does not need yet.

1const bytes = new Uint8Array([0,97,115,109,1,0,0,0,1,7,1,96,2,127,127,1,127,3,2,1,0,7,7,1,3,97,100,100,0,0,10,9,1,7,0,32,0,32,1,106,11]);2const sections = [3  ["header and version", 0, 8],4  ["type", 8, 18],5  ["function", 18, 22],6  ["export", 22, 31],7  ["code", 31, 41],8];9 10for (const [name, start, end] of sections) {11  console.log(name, bytes.slice(start, end).length);12}

Line 1 holds the same 41 bytes. Lines 3 through 7 label byte ranges: header and version, type, function, export, and code. The loop on line 10 prints each label with its size, so it shows header and version 8 first and code 10 last. The labels are a teaching map, not a general binary parser.

You usually do not write these bytes by hand. A compiler emits them. The text format below, called WAT, is a readable version of the same simple idea. It declares two 32-bit integer parameters, adds them, and exports the function.

(module
  (func $add (param i32 i32) (result i32)
    local.get 0
    local.get 1
    i32.add)
  (export "add" (func $add)))

1const bytes = new Uint8Array([0,97,115,109,1,0,0,0,1,7,1,96,2,127,127,1,127,3,2,1,0,7,7,1,3,97,100,100,0,0,10,9,1,7,0,32,0,32,1,106,11]);Run2const { instance } = await WebAssembly.instantiate(bytes);3console.log(instance.exports.add(2, 3));

1const bytes = new Uint8Array([0,97,115,109,1,0,0,0,1,7,1,96,2,127,127,1,127,3,2,1,0,7,7,1,3,97,100,100,0,0,10,9,1,7,0,32,0,32,1,106,11]);2const sections = [3  ["header and version", 0, 8],Run4  ["type", 8, 18],5  ["function", 18, 22],6  ["export", 22, 31],7  ["code", 31, 41],8];9 10for (const [name, start, end] of sections) {11  console.log(name, bytes.slice(start, end).length);12}

Loading and calling modules

Instantiation creates a usable instance of a module. An instance has exports: functions, memories, tables, or globals that JavaScript can use. Before you instantiate unknown bytes, WebAssembly.validate can cheaply tell you whether they have valid Wasm structure.

1const bytes = new Uint8Array([0,97,115,109,1,0,0,0,1,7,1,96,2,127,127,1,127,3,2,1,0,7,7,1,3,97,100,100,0,0,10,9,1,7,0,32,0,32,1,106,11]);2const broken = new Uint8Array([0, 97, 115, 109]);3console.log(WebAssembly.validate(bytes));4console.log(WebAssembly.validate(broken));

Line 1 contains the valid add module. Line 2 contains only a partial header. Lines 3 and 4 print true and false. Validation does not run the module and does not promise that its behavior is useful; it only checks the Wasm format.

When bytes come from a file, streaming lets the browser compile while the response arrives. The server must deliver the file with the correct application/wasm MIME type, so this example is a fragment rather than an editor-run snippet.

const { instance } = await WebAssembly.instantiateStreaming(
  fetch("add.wasm"),
);
console.log(instance.exports.add(2, 3));

Line 1 starts a fetch and hands its response to instantiateStreaming. Line 4 calls the export after the awaited instance exists. Imports flow in the other direction: JavaScript can supply functions or memory in the second argument to instantiation, and Wasm can call those imports through its declared interface.

Liftoff and tiered compilation

Wasm bytes are not machine code for every computer. In V8, the engine turns Wasm instructions into machine code. Liftoff is V8's fast baseline compiler: it makes usable code quickly, so an application can start. It is deliberately simple and has less room for deep optimization.

1function chooseTier(calls) {2  return calls >= 3 ? "TurboFan" : "Liftoff";3}4 5console.log(chooseTier(1));6console.log(chooseTier(3));

Line 1 models a call count. Line 2 chooses the baseline name before three calls and the optimizing name from three calls onward. The model prints Liftoff and then TurboFan. It is only a teaching model: real engines use their own thresholds and scheduling.

1function describeTier(calls) {2  if (calls === 0) return "not called";3  if (calls < 3) return "Liftoff baseline";4  return "TurboFan candidate";5}6 7console.log(describeTier(0));8console.log(describeTier(1));9console.log(describeTier(3));

Line 1 describes code that has not run. Line 2 labels early calls as a Liftoff baseline, and line 3 says later calls are a TurboFan candidate. The three logs show the timeline without pretending that V8 upgrades at a fixed call count.

V8's current pipeline documentation says functions are initially compiled by Liftoff when called, then hot functions can be recompiled by TurboFan on a background thread. TurboFan takes more passes and can improve register allocation, eliminate redundant work, and inline. A currently running Liftoff call finishes as Liftoff code; later calls can use optimized code. See tiered compilation for the same idea across JavaScript engines.

Sharing linear memory

Linear memory is a contiguous buffer of bytes. A Wasm module can import a memory created by JavaScript, or export a memory it created. JavaScript uses a typed-array view such as Uint8Array to read and write those exact bytes. This avoids copying every byte through a separate JavaScript object.

1const memory = new WebAssembly.Memory({ initial: 1 });2const oldView = new Uint8Array(memory.buffer);3oldView[12] = 42;4console.log(memory.buffer.byteLength, oldView[12]);5memory.grow(1);6console.log(memory.buffer.byteLength, oldView.byteLength);

Line 1 creates one page. A Wasm page is 65536 bytes, so line 4 first prints 65536 42. Line 5 grows by one page. Line 6 then prints 131072 0: the current memory is two pages and the old non-shared view is detached.

After grow, make a fresh view from memory.buffer. For multi-byte numbers, use DataView and specify little-endian order because Wasm memory is always little-endian. A shared Wasm memory is a separate advanced feature with stronger browser security and synchronization requirements.

1const memory = new WebAssembly.Memory({ initial: 1 });2const view = new DataView(memory.buffer);3 4view.setUint16(0, 500, true);5console.log(view.getUint8(0), view.getUint8(1));6console.log(view.getUint16(0, true));

Line 1 creates the bytes and line 2 gives JavaScript a DataView. Line 4 writes the number 500 in little-endian order. Lines 5 and 6 print 244 1 and 500: the low byte comes first, while the view reconstructs the original number.

1const memory = new WebAssembly.Memory({ initial: 1 });Run2const oldView = new Uint8Array(memory.buffer);3oldView[12] = 42;4console.log(memory.buffer.byteLength, oldView[12]);5memory.grow(1);6console.log(memory.buffer.byteLength, oldView.byteLength);

1const memory = new WebAssembly.Memory({ initial: 1 });2const oldView = new Uint8Array(memory.buffer);3oldView[12] = 42;4console.log(memory.buffer.byteLength, oldView[12]);5memory.grow(1);6console.log(memory.buffer.byteLength, oldView.byteLength);

WasmGC

Traditional Wasm modules use linear memory, which is untyped bytes. Languages with their own garbage collectors often compile that collector into the module too. WasmGC adds VM-managed structs and arrays so a toolchain can represent objects using the host's garbage collector instead.

This is especially useful for garbage-collected languages such as Kotlin, Dart, and Java. Rather than shipping a second collector and object runtime in every Wasm file, a compatible toolchain can use the browser VM's managed objects. That can reduce code size and lets the VM understand object types more directly.

It is still a compiler-target decision, not a JavaScript feature you sprinkle into app code. A language needs a toolchain that emits WasmGC instructions, and its runtime semantics still need careful design. V8 reported WasmGC shipped in Chrome 119; do not assume one engine's version tells you every browser's support without checking its compatibility data.

A web app can feature-detect the basic Wasm API before choosing an optional path. That check answers only whether the host exposes the core JavaScript interface; a production app should still test the exact module or advanced proposal it plans to load.

1const canUseWasm = typeof WebAssembly === "object" &&2  typeof WebAssembly.instantiate === "function";3 4console.log(canUseWasm);5console.log(typeof WebAssembly.Memory === "function");

Lines 1 and 2 check the global object and its instantiate method. Line 4 prints whether the basic API is available, and line 5 separately checks the memory constructor. Both print true in a modern browser with WebAssembly support.

JavaScript Promise Integration

Web APIs such as fetch return Promises, but many native programs are written in a straight, synchronous style. JavaScript Promise Integration, or JSPI, lets a Wasm call suspend when an imported JavaScript function returns a Promise, then resume when that Promise settles.

1// Illustration only: JSPI is usually produced by a Wasm toolchain.2async function askForPrice() {3  return Promise.resolve(12);4}5 6console.log(await askForPrice());

Line 2 returns a Promise that resolves to 12. Line 5 awaits it and prints 12. This is not a hand-written JSPI module; it is the small Promise shape that a Wasm toolchain can bridge. Toolchains wrap imports and exports during instantiation so a synchronous-looking Wasm function can pause and later continue.

The V8 JSPI announcement says the feature reached WebAssembly phase 4 and is available in Chrome 137 and Firefox 139. JSPI does not suspend normal JavaScript call stacks. JavaScript already has async, await, and Promises for its own asynchronous code.

Choosing Wasm for a real app

Start with a user-visible problem and a measurement. If image resizing makes a photo editor slow, profile the resize loop. If it dominates time and has a compact numeric interface, it may be a useful Wasm candidate. If a click handler is slow because of network latency or DOM layout, Wasm is unlikely to help.

Keep the first boundary small. Pass one typed array or a few numbers, call one export, and measure before and after. Repeatedly converting complicated JavaScript objects or copying large arrays can erase the gain from faster compute work.

1function resizeNearest(pixels, sourceWidth, targetWidth) {2  const result = new Uint8Array(targetWidth);3 4  for (let index = 0; index < targetWidth; index += 1) {5    const sourceIndex = Math.floor(index * sourceWidth / targetWidth);6    result[index] = pixels[sourceIndex];7  }8 9  return result;10}11 12const pixels = new Uint8Array([10, 20, 30, 40]);13console.log([...resizeNearest(pixels, 4, 2)].join(","));

Line 1 models the compact resize function a module could export. Line 2 creates the output pixels, lines 4 through 6 choose each source pixel, and line 13 logs 10,30. A real app can keep its buttons and preview in JavaScript while passing one image buffer to a Wasm resize routine.

The model is deliberately JavaScript so it can run here. The design lesson is the boundary: pass typed data once, perform the repeated math together, then return typed data once. Replace it with compiled Wasm only after profiling shows that this particular loop dominates the user-visible delay.

For concurrency around heavy work, see shared memory and parallel patterns. Those lessons explain worker coordination; this one explains the JavaScript-to-Wasm boundary.

Common misconceptions

• “Wasm replaces JavaScript.” It is usually a focused compute component called from JavaScript.
• “Wasm is automatically faster.” Boundary overhead, download size, and the actual bottleneck matter.
• “A Wasm page is an object heap.” Linear memory is bytes; code must agree on layout.
• “All engines use Liftoff.” Liftoff is V8 terminology, so describe it as a V8 pipeline detail.
• “JSPI replaces async JavaScript.” It bridges Wasm to Promise-returning JavaScript APIs.

Practice exercises

const add = (left, right) => left + right;
console.log(add(2, 3));

WebAssembly.validate(bytes)

const memory = new WebAssembly.Memory({ initial: 1 });
console.log(memory.buffer.byteLength);

Check your understanding

Answer by tracing the JavaScript-to-Wasm boundary: who loads, who computes, which bytes are shared, and when a feature belongs in a toolchain.

Key takeaways

• Wasm is a typed binary target that JavaScript loads and calls for focused work.
• Use validation for format checks, instantiation for in-memory bytes, and streaming for fetched modules.
• V8 uses Liftoff for quick baseline Wasm code and TurboFan for hot-code optimization.
• Linear memory is shared bytes; make a new view after ordinary growth.
• WasmGC helps compatible garbage-collected language toolchains use VM-managed Wasm objects.
• JSPI bridges synchronous-looking Wasm code to Promise-returning JavaScript APIs.

Coming next: How to read ECMAScript