Skip to main content

WAST language guide

WAST is a typed source language for writing a single WebAssembly module. It is intentionally close to WebAssembly: source types, structured control, GC heap types, and low-level instructions all have a visible relationship to the output module.

This guide explains the language through examples. For normative grammar, validity rules, lowering requirements, and feature gates, use the authoritative specification. Before you rely on any of this, read Limitations and rough edges — it covers what's missing, what's thinly tested, and where past bugs have hidden.

The shape of a module​

A source file is a WebAssembly module. Declarations define functions, types, globals, tables, memories, imports, exports, and an optional start function.

global Counter: mut i32 = 0;

func increment() -> i32 {
  Counter = Counter + 1;
  return Counter;
}

export func increment as "increment";

The WebAssembly ABI name is always explicit. The source name and exported name do not need to match.

Trying it​

Save the example above as counter.wast and compile it:

$ wastc build counter.wast
wastc: catalog wastc-core-gc-0 -> counter.wat

counter.wat is readable WebAssembly Text, with comments tracing each instruction back to the WAST source that produced it:

;; wastc catalog: wastc-core-gc-0
(module
  ;; func increment(...)
  (func $increment
    (result i32)
    ;; Counter = Counter + 1;
    (global.set $Counter (i32.add (global.get $Counter) (i32.const 1)))
    ;; return Counter;
    (return (global.get $Counter)))
  ;; global Counter: ... = ...;
  (global $Counter (mut i32) (i32.const 0))
  ;; export func increment as "increment";
  (export "increment" (func $increment)))

Or skip the install and try it right here — edit the source below and the compiled WAT updates as you type, using the same compiler compiled to WebAssembly:

Loading playground…

The playground has more examples to load, covering GC types, control flow, and raw wasm.* operations. See command-line interface for wastc check (diagnostics without writing a file) and wastc lsp (editor integration).

What WAST targets​

The initial language target includes:

  • WebAssembly core instructions and numeric value types.
  • Multi-value functions and structured blocks.
  • Reference types and WebAssembly GC structs, arrays, i31, casts, and tests.
  • Typed low-level wasm.<opcode> operations for the selected instruction catalog.

Exception handling, SIMD, threads, memory64, runtime strings, and other proposals are not implemented. Tail calls exist only as a compiler output flag, not source syntax. See Limitations for the complete list.

Where to go next​

Reference, for looking things up rather than reading through:

Guide, for learning the feature in context: