Page plan · 12 pages

Written for: front-end engineers new to WebAssembly

1. 1

   WebAssembly for front-end engineers

   • This primer shows front-end engineers how WebAssembly fits beside JavaScript in the browser.
   • WebAssembly is a compact binary instruction format that runs in a sandboxed virtual machine.
   • We will cover loading, memory, imports and exports, the text format, calls and errors.
   • Goal: leave able to load a small module and call it from JavaScript.
2. 2

   Why WebAssembly exists

   • JavaScript is flexible, but its dynamic nature makes predictable performance hard for heavy computation.
   • WebAssembly gives a typed, low-level compilation target for languages like C, C++ and Rust.
   • Existing native code libraries can be reused on the web instead of rewritten.
   • It complements JavaScript rather than replacing it; JavaScript still handles the DOM and glue.
3. 3

   The stack from browser to machine

   • At the top sits your source code, written in a language such as Rust or C++.
   • A compiler turns it into a .wasm binary module.
   • The browser engine validates the module and compiles it to native machine code.
   • The module runs sandboxed and reaches the outside world only through JavaScript APIs.
4. 4

   Fetching, compiling and instantiating a module

   • First, fetch the .wasm file like any other network resource.
   • Then compile the bytes into a WebAssembly.Module, which validates them.
   • Instantiating the module produces an Instance holding its exports and memory.
   • WebAssembly.instantiateStreaming compiles while the response downloads, and needs the application/wasm MIME type.
5. 5

   Linear memory: one resizable array of bytes

   • Linear memory is a single contiguous array of bytes that the module reads and writes.
   • JavaScript sees it as an ArrayBuffer, so typed arrays can view the same bytes.
   • Memory is sized in 64 KiB pages and can grow with memory.grow.
   • Growing memory can detach the old buffer, so re-create your typed array views afterward.
6. 6

   Imports and exports between a module and JavaScript

   • A module declares imports, the functions or values it needs from the host.
   • Exports are the functions, memory and globals the module offers to JavaScript.
   • Imports are supplied in an import object when you instantiate the module.
   • This boundary is how a module logs, draws or touches the DOM indirectly.
7. 7

   Reading the WAT text format

   • WAT is the human-readable text form of the binary format.
   • It uses S-expressions: nested parentheses such as (module (func ...)).
   • Functions declare typed parameters and results, like (param i32) (result i32).
   • Instructions operate on a stack, for example local.get pushes a value and i32.add pops two.
8. 8

   Step by step through a call

   • JavaScript calls an exported function with arguments.
   • Arguments are converted to WebAssembly types such as i32 or f64.
   • The function's instructions run on the engine's stack machine.
   • The result is converted back to a JavaScript value and returned to the caller.
9. 9

   An annotated walkthrough of a small module

   • Our example module exports a function that adds two i32 numbers.
   • The func line declares two i32 parameters and one i32 result.
   • The body pushes both parameters with local.get, then applies i32.add.
   • An export line gives the function a name that JavaScript can call.
10. 10

    Calling exported functions from JavaScript

    • After instantiation, exports appear on instance.exports as ordinary callable functions.
    • Call them like JavaScript functions, for example instance.exports.add(2, 3).
    • Numbers pass directly; strings and objects must be encoded into linear memory.
    • Keep calls coarse-grained, since many tiny crossings between JavaScript and Wasm add overhead.
11. 11

    Traps: what happens when a module fails

    • A trap is an immediate abort when a module does something illegal.
    • Examples include out-of-bounds memory access, integer divide by zero and the unreachable instruction.
    • In JavaScript a trap surfaces as a WebAssembly.RuntimeError exception.
    • You can catch it with try/catch, but the module's state may no longer be trustworthy.
12. 12

    Support across today's major browsers

    • WebAssembly's core features run in all current major browsers: Chrome, Firefox, Safari and Edge.
    • Newer proposals, such as threads or garbage collection, ship at different times.
    • Feature-detect optional features before relying on them.
    • Check a compatibility table like MDN's for the exact features your audience needs.