Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 38 ยท Patterns and Tooling

The WebAssembly Toolchain

Tour the WebAssembly toolchain - wat2wasm, wasm-objdump, wasm-opt, wasm-tools, twiggy, wasm-pack - then build a module byte by byte and write a mini section inspector in JavaScript.

Compilers like emcc and cargo get all the attention, but a working WebAssembly developer uses a second group of tools every day: programs that assemble, disassemble, inspect, validate, optimize and compose modules. Knowing what each one does saves hours when a build misbehaves, a binary is too big, or a module fails to load and the only clue is a CompileError.

This lesson maps the toolchain, and then makes it concrete by doing in JavaScript what several of those tools do: assembling a module from bytes, and inspecting a module's sections, imports and exports. After this, binary files will not feel like black boxes.

The tool families

The main toolkits

WABT wat2wasm, wasm2wat, wasm-objdump.
Binaryen wasm-opt, wasm-dis, wasm2js.
wasm-tools Parse, validate, compose components.
twiggy Find what makes a module big.

Install one, learn the others on demand.

1 / 2
Task Tool and command
Text to binary wat2wasm add.wat -o add.wasm (WABT)
Binary to text wasm2wat add.wasm -o add.wat (WABT) or wasm-dis (Binaryen)
List sections and sizes wasm-objdump -h add.wasm (WABT)
List imports and exports wasm-objdump -x add.wasm
Disassemble with code wasm-objdump -d add.wasm
Validate wasm-validate add.wasm, wasm-tools validate add.wasm
Optimize wasm-opt -O3 in.wasm -o out.wasm (Binaryen)
Strip names and debug info wasm-strip add.wasm (WABT)
Decompile to C-like code wasm-decompile add.wasm
Wrap as component wasm-tools component new core.wasm -o app.wasm
Size analysis twiggy top app.wasm
Convert to JavaScript (legacy) wasm2js add.wasm -o add.js
Run wasmtime, wasmer, node, deno

A helpful workflow is the round trip: compile your program, run wasm2wat on the result, and read the text. When a size or speed question comes up, the text format answers it directly. See the text-format lessons earlier in this track for the syntax.

Online tools also exist: the WABT demo site converts text and binary in the browser, and wasm-tools has a playground. They are handy for experiments, but the command-line tools are scriptable, which matters for CI.

Assembling a module byte by byte

A text-format assembler such as wat2wasm ends up emitting the same structure every time: a header, then sections made of an id, a LEB128 size and a payload. If you understand that, you can write a minimal assembler yourself. This one builds a module with two exported functions, add and mul, each (i32, i32) -> i32:

WAT
(module
  (func (export "add") (param i32 i32) (result i32) local.get 0 local.get 1 i32.add)
  (func (export "mul") (param i32 i32) (result i32) local.get 0 local.get 1 i32.mul))
Node.js A minimal assembler

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

That is the entire format for a small module. Real assemblers add imports (section 2), memory (5), globals (6), tables (4), data segments (11), the start function (8) and custom sections (0), but the structure is identical. Writing even a few sections by hand cures most of the mystery.

Inspecting a module: your own wasm-objdump

The reverse direction is just as useful: given bytes, report the sections, imports and exports. The JavaScript API gives you WebAssembly.Module.imports and exports, but walking the binary yourself also gives section sizes, which is what you need when hunting for bloat. This inspector prints a section table similar to wasm-objdump -h, then decodes the export section:

Node.js A mini wasm-objdump

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Look at the section table: the code section dominates, as it usually does, and sections appear in the fixed order the format requires. Adding a name custom section (see Debugging WebAssembly) would show up here as custom "name".

A sensible project setup

A typical repository for a Wasm library has this shape:

TEXT
my-lib/
  src/            source in C, Rust, AssemblyScript...
  wit/            interface definitions, if you use components
  build.sh        compile, wasm-opt, wasm-strip
  tests/          run the module in Node or Wasmtime
  dist/           final .wasm and generated JS glue
  .github/workflows/ci.yml

And a build script that makes the whole chain reproducible:

Terminal
#!/usr/bin/env bash
set -euo pipefail
cargo build --release --target wasm32-unknown-unknown
wasm-bindgen --target web --out-dir dist target/wasm32-unknown-unknown/release/my_lib.wasm
wasm-opt -Oz --enable-bulk-memory dist/my_lib_bg.wasm -o dist/my_lib_bg.wasm
wasm-validate dist/my_lib_bg.wasm
ls -l dist/my_lib_bg.wasm

In CI, run wasm-validate, run the tests, and fail the build if the compressed size grows past a budget. A size check such as gzip -c dist/my_lib_bg.wasm | wc -c compared with a limit catches the accidental 500 KB dependency before it ships.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which tool converts a .wasm binary back to the text format?

    wasm2wat disassembles a binary to text; wat2wasm does the opposite.
  2. 2. Which tool shows which functions contribute most to a module's size?

    twiggy analyzes a binary and lists functions and their retained sizes.
  3. 3. How is every section in a wasm binary laid out?

    That uniform id, size, payload layout lets tools skip sections they do not care about.
  4. 4. Which toolkit contains wasm-opt?

    wasm-opt belongs to Binaryen. wasm-pack and Emscripten call it for you.

Summary

  • Four toolkits cover most needs: WABT (assemble, disassemble, inspect), Binaryen (optimize), wasm-tools (parse, validate, compose components) and twiggy (size analysis).
  • Binaries are a header plus sections with an id, LEB128 size and payload; a small assembler or inspector fits in a few dozen lines.
  • Validate in CI, test the built artifact, and keep a size budget.
  • Use the round trip (wasm2wat) to answer "what did the compiler really produce?".

Next: Bundlers and Loading Strategies