Wax
Wax is a Rust-like syntax for WebAssembly. Write Wasm (including WasmGC) in a familiar, expression-oriented notation, and convert between Wax, WebAssembly Text (WAT), and the binary format, in any direction.
Where the WebAssembly text format spells out a stack machine:
(func $add (param $x i32) (param $y i32) (result i32)
local.get $x
local.get $y
i32.add)
Wax reads like a programming language:
fn add(x: i32, y: i32) -> i32 {
x + y;
}
Both compile to identical bytecode.
Try it in your browser: type Wax, see the WAT and diagnostics live, with no install.
The payoff grows with the program: struct types, nullable references, casts, and loops stay readable where the equivalent WAT sprawls:
type list = { value: i32, next: &?list };
#[export = "sum"]
fn sum(l: &?list) -> i32 {
let total: i32 = 0;
while l is &list {
total += l.value;
l = l.next;
}
total;
}
The WAT this compiles to (wax sum.wax -f wat)
(type $list (struct (field $value i32) (field $next (ref null $list))))
(func $sum (export "sum") (param $l (ref null $list)) (result i32)
(local $total i32)
(local.set $total (i32.const 0))
(loop $loop
(if (ref.test (ref $list) (local.get $l))
(then
(local.set $total
(i32.add (local.get $total)
(struct.get $list $value (local.get $l))))
(local.set $l (struct.get $list $next (local.get $l)))
(br $loop))))
(local.get $total)
)
Highlights
- Full WebAssembly 3.0: garbage collection, exception handling, tail calls, multiple and 64-bit memories, SIMD, plus stack switching, threads, wide arithmetic, and branch hints on by default. See Feature Support.
- Every direction: all 9 conversions between
wax, wat, and wasm work, including decompiling an arbitrary .wasm binary into readable Wax. A real type checker: errors are caught before any output is produced, and reported with source context:
Error: This operator cannot be applied to operands of types i32 and f64.
──➤ hello.wax:3:7
1 │ #[export = "add"]
2 │ fn add(x: i32, y: f64) -> i32 {
3 │ x + y;
· ^
4 │ }
- A toolchain, not just a compiler: a formatter (
wax format), a validator (wax check), configurable lints (-W), conditional compilation (-D), and source maps for debugging the generated Wasm in the browser.
Quick start
wax input.wax -o output.wasm # compile Wax to a Wasm binary (auto-detected from .wasm)
wax input.wat # convert WAT to Wax (to stdout)
wax program.wasm # decompile a binary to Wax
wax check input.wax # type-check only, no output
wax format -i input.wax # reformat in place
The input format is detected from the file extension (override with -i); the default output format is wax (override with -f). wax reads from stdin when no input file is given and writes to stdout when -o is omitted.
See the CLI reference for the complete set of options.
Editor support
Editor integrations live under editors/, all sharing the same analysis:
- Visual Studio Code (on the Marketplace): a full extension for
.wax and .wat, with syntax highlighting, formatting, snippets, side-by-side compile/decompile previews, and the complete language-server feature set. It runs the toolchain compiled to WebAssembly in-process, so it works the same in desktop and web VS Code. - Neovim, Helix, and Emacs: the
tree-sitter-wax grammar for highlighting, plus the built-in wax lsp language server for diagnostics, hover, go to definition, find references, rename, completion, and signature help.
Any other editor with a Language Server Protocol client gets the same features by launching wax lsp. See the documentation for setup details.
Installation
npm
The easiest way to get wax is from npm; it ships a single cross-platform WebAssembly build that runs on any Node 22+ (Linux, macOS, Windows):
npm install -g @wax-wasm/wax
Prebuilt binaries
Native wax executables for Linux, macOS (Apple silicon and Intel), and Windows (with SHA256SUMS) are attached to each release. Download the one for your platform, make it executable, and put it on your PATH:
curl -LO https://github.com/ocsigen/wax/releases/latest/download/wax-linux-x86_64
chmod +x wax-linux-x86_64 && mv wax-linux-x86_64 /usr/local/bin/wax
The edge prerelease carries the same binaries built from the latest main, rebuilt on every push.
opam
wax is published on the opam repository, so if you have an OCaml toolchain it builds and installs with:
opam install wax
From source
Requirements: Opam (2.1+) and OCaml 4.14+. The toolchain builds on OCaml 4.14; running the full test suite requires 5.0+ (it uses Domain).
# Install dependencies
opam install . --deps-only
# Build
dune build
# Run tests
dune runtest
# Install
opam install .
Documentation
Full documentation is available at ocsigen.org/wax/: a language guide, the Wax↔WebAssembly correspondence, examples, and the CLI reference. You can also build it locally with mdbook build docs (requires mdBook).
AI coding agents
Wax has almost no presence in model training data, so the repository ships a wax agent skill that gives a coding assistant the complete language reference and has it validate everything it writes with wax check. For agents that support the SKILL.md format (Claude Code, Antigravity, Copilot, Codex, ...), install it with the skills CLI:
npx skills add ocsigen/wax
or copy skills/wax/ into the agent's skills directory (for Claude Code, .claude/skills/).
Correctness
Wax is built to be trusted with your binaries:
- It passes the official WebAssembly spec test suite.
- It is fuzzed against the reference interpreter and
wasm-tools, which must agree with Wax on which modules are valid. - Converting a module to Wax and back must reproduce its exact behaviour, verified by re-running the spec tests on round-tripped modules.
See fuzz/README.md for how the harness works.
Contributing
Contributions are welcome! See CONTRIBUTING.md for the submission process, the data-flow overview, and the checklists for changing the AST or adding syntax.
Wax is licensed under Apache-2.0.
