Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 38 · WASI and Beyond the Browser

The WebAssembly Component Model and WIT

Learn the WebAssembly Component Model - WIT interfaces and worlds, the canonical ABI that lifts and lowers strings and records, composition, wasm-tools, jco and cargo-component - with runnable stand-ins.

Core WebAssembly modules speak only numbers. In the lessons so far you wrote glue code to move strings and structs across the boundary, and that glue had to match a particular compiler's memory layout exactly. A Rust module and a C module might both export "a function taking a string" yet need completely different calling code. This is the main thing standing between WebAssembly and a world where libraries written in different languages plug together.

The Component Model solves it by adding a layer above core modules. A component is a package that declares its interface in a language-neutral way, using rich types: strings, lists, records, variants, options and results. The standard defines exactly how those types are laid out in memory (the canonical ABI), so any host or any other component can call it without custom glue.

Core modules versus components

Core module Component
Types in its interface i32, i64, f32, f64 Strings, lists, records, variants, options, results, resources
Who writes the glue You, per language Tools, from the interface description
Can contain Functions, memory, tables Core modules plus adapters, and other components
Linking By name, by hand By typed interface, checked ahead of time
File format .wasm core binary .wasm component binary (different encoding)

A component usually wraps one or more core modules. The core modules do the real work; the component layer describes and adapts their interface.

Why components?

Rich types Strings, records, lists, results.
Any language Rust calls C, JS calls Go.
Shared nothing Each component keeps its own memory.
Composable Plug components together safely.

One interface, no hand-written glue.

1 / 2

WIT: describing an interface

WIT (WebAssembly Interface Types) is a small text language. You group functions and types into an interface, then declare a world, which lists everything a component imports (needs from the host) and exports (offers).

WIT
package example:[email protected];

interface shapes {
  record point {
    x: s32,
    y: s32,
  }

  variant error {
    out-of-range(u32),
    invalid(string),
  }

  distance-squared: func(p: point) -> s32;
  shout: func(text: string) -> string;
  parse-point: func(input: string) -> result<point, error>;
  find-nearest: func(origin: point, candidates: list<point>) -> option<point>;
}

world geometry-service {
  import wasi:logging/logging;   // something the host must provide
  export shapes;                 // what this component offers
}

Names use kebab-case, and the types read as you would hope: option<point>, list<point>, result<point, error>, tuples, enums, flags, and resource types for handles with methods and destructors. There are no pointers or lengths in sight.

The canonical ABI: lift and lower

How does a string get from one component to another when each has its own private memory? The canonical ABI defines two operations:

  • Lower converts a high-level value into core-module numbers in the callee's memory: allocate a buffer through the callee's exported realloc, copy the UTF-8 bytes, pass pointer and length.
  • Lift is the reverse: read the pointer and length the callee returned and build a high-level value.

This is exactly the manual work from Passing Strings and Structs Across the Boundary, now written down as a standard, so it can be generated once for every language. A generated "adapter" does the lowering and lifting between components or between a component and the host. You can build a miniature of it. The guest module here has an allocator and an in-place upper; the adapter below makes it look like a function shout(text: string) -> string:

Node.js Lowering and lifting a string by hand

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.

The caller of shout never sees a pointer. That is the promise of the component model: the boundary is typed, and the plumbing is generated and standardized.

Records, options and results in memory

A record is laid out like a C struct, with fields in order and aligned to their size. Sum types (option, result, variant) are stored as a discriminant (a small integer saying which case) followed by the payload of that case, aligned for the largest case. Here is the point record from the WIT above lowered by hand into the memory of a module that computes dist2 (the structs lesson's module), together with the layouts of option and result:

Node.js Lowering a record, an option and a result

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.

You will never write these helpers in a real project: wasm-tools, jco and the language toolchains generate them from the WIT file. But knowing the layout explains the error messages and the performance characteristics (strings and lists are copied across the boundary; there is no shared object graph).

Composition and shared-nothing

Each component has its own memory. Two components cannot see each other's bytes; they exchange values, copied through lift and lower. That has two consequences. First, a bug or exploit in one component cannot read the memory of another, which makes mixing code from different authors safer. Second, you can combine components into a larger one: a Rust HTTP handler, a Go image resizer and a JavaScript validation library can be composed into one .wasm file, with the tool verifying that every import is matched by a compatible export.

Tooling

Tool Purpose
wasm-tools component new core.wasm -o app.wasm Wrap a core module as a component
wasm-tools component wit app.wasm Print the WIT of a component
wasm-tools compose / wac Link components together
cargo component / wasm32-wasip2 target Build components from Rust
jco componentize / jco transpile Build components from JavaScript, or run a component in the browser by generating glue
wit-bindgen Generate bindings for C, C++, Go, Rust, C# and more
wasmtime Run components with WASI Preview 2

Browsers do not yet run components natively, so jco transpile converts a component into core modules plus JavaScript glue that performs the lifting and lowering. Server runtimes such as Wasmtime run components directly.

Check your understanding

Quick check · 4 questions

of 4 answered You scored / 4 · perfect!

  1. 1. What problem does the Component Model mainly solve?

    Components describe interfaces with rich types and a standard memory layout, so different languages can interoperate.
  2. 2. What is a WIT world?

    A world is the full contract of a component: the host features it needs and the interfaces it provides.
  3. 3. What does lowering a string do in the canonical ABI?

    Lowering turns a high-level value into core wasm values, here allocating in the callee and copying the bytes.
  4. 4. Why are components called shared-nothing?

    No component can read another's memory, which improves isolation and safety.

Summary

  • The Component Model adds typed, language-neutral interfaces on top of core modules.
  • WIT describes interfaces and worlds; the canonical ABI defines how strings, records, options, results and lists are lowered into and lifted out of linear memory.
  • Components do not share memory; values are copied across boundaries, which isolates them and allows safe composition.
  • Tools (wasm-tools, wit-bindgen, cargo component, jco) generate the glue; Wasmtime runs components, and jco transpile brings them to browsers.
  • WASI Preview 2 is defined as a set of WIT interfaces on this model.

Next: WebAssembly on Servers and the Edge