A layered stack for compiling Julia to WebAssembly using wasm's GC proposal, with wasmtime as the reference execution engine and the browser as the ultimate target.
Live demos, compiled from Julia's optimized IR and running entirely client-side:
- the
JuliaSyntax.Tokenizelexer, tokenizing as you type: https://kenoaistaging.github.io/experiment-fable-julia-wasm/ - the complete
JuliaSyntax.jlparser with a live parse tree (Monaco editor, nested node boxes, synced outline): https://kenoaistaging.github.io/experiment-fable-julia-wasm/parser.html
| Package | Purpose |
|---|---|
WasmTools/ |
Pure-Julia reader/writer for wasm binaries. Full wasm 3.0: WasmGC (struct/array/ref types, rec groups, subtyping), function references, tail calls, exception handling, bulk memory, multi-memory. Byte-stable round trips; fuzzed against wasm-tools smith. Zero dependencies. |
WasmtimeRunner/ |
Embeds wasmtime via Wasmtime_jll (pinned to v45): load/validate/instantiate modules, call exports, define host functions backed by Julia callables, bind Julia values into wasm as externref. Traps and engine errors surface as Julia exceptions. |
WasmCodegen/ |
Translator from Julia's optimized SSA IR to wasm. Engine-agnostic (depends only on WasmTools + vendored UnicodeNext). Untranslatable callees become offload imports — host functions calling back into native Julia — so partial programs run end-to-end while the compiler grows. |
JSRuntime/ |
Browser-runtime types. JSString is a JS-native string (externref) whose operations compile to the js-string builtins ("wasm:js-string" imports) — near-native JS string ops in the browser; the same modules run under wasmtime with the package's native UTF-16 implementations bound as imports. |
# julia --project=. (the top-level environment devs all three packages)
using WasmCodegen, WasmtimeRunner
fib(n::Int64) = n <= 1 ? n : fib(n - 1) + fib(n - 2)
comp = compile_wasm(fib, Tuple{Int64}) # comp.bytes is the wasm binary
eng = Engine(); store = Store(eng)
inst = instantiate(store, CompiledModule(eng, comp.bytes))
inst["fib"](20) # 6765, computed inside wasmtimeThe same bytes run on V8: julia --project=. examples/node_differential.jl
checks native Julia, wasmtime, and Node against each other.
- all Julia scalars (sub-word integers with a sign-correct i32 discipline,
Charas raw bits, arbitrary primitive types), full arithmetic with Julia's exact semantics: total shifts, checked overflow tuples, bit ops, conversions - arbitrary control flow (dispatcher-loop lowering, any CFG), recursion and
mutual recursion across
:invokeedges - WasmGC: structs/tuples → GC structs (packed i8/i16 fields), mutable
identity (
===isref.eq),Memory{T}/Vector→ GC arrays (push!andcopycompile with zero offloads),Union{Nothing,T}→ nullable refs, general small unions of concrete types →anyrefwith per-type boxes - wasm-resident strings:
Stringis a GC byte array (the WIT array+size model, with GC instead of linear memory) —codeunit/ncodeunits/==/sizeofare in-wasm array ops, literals live in passive data segments, andInt128is a{lo,hi}struct. At the boundary strings externalize (extern.convert_any); hosts read/build them via exported__str_*accessors - try/catch/finally via wasm-EH: per-block
try_tablerouted to the innermost handler;÷0, overflow, bounds errors, and explicit throws are catchable insidetry - overlay interpreter: a custom
AbstractInterpreterreplaces pointer-based Base primitives before inlining — memcpy/memset/memcmp patterns becomearray.copy/loops, and unicode classification (category_code, identifier predicates, grapheme breaks) compiles in-wasm via vendored UnicodeNext - host constants: Symbol literals become imported
externrefglobals; string/mutable constant tables (Dict,Vector,Memory) materialize as wasm globals via a start function, large tables as data segments - offloading: callees with scalar/externref/String boundaries (including
Union{Nothing,scalar}returns) become"julia"imports bound to native thunks —parse,string(n, base=16),exp/sin/logrun with one or two leaf offloads
Not yet: binding the caught exception value (catch e with e used),
exception propagation across compiled-function call boundaries, Any-typed
values, dynamic dispatch, closures as values, RadixSort internals (default
sort!; InsertionSort compiles).
examples/lexer/ compiles the real JuliaSyntax.Tokenize lexer (no manual
porting) into a 1.1MB module with two host imports: the token sink and
=== on Symbol constants (source text lives in wasm as a GC byte array).
Token streams match the native lexer exactly across unicode operators,
interpolated/triple strings, all numeric literal forms, and malformed input —
verified under wasmtime (examples/lexer/run_wasmtime.jl) and V8
(examples/web/test_node.mjs). Rebuild the web demo with
examples/lexer/build_web.jl.
examples/parser/ goes further: the complete JuliaSyntax.jl
recursive-descent parser (error recovery and token validation included)
streams its native (token, range) events out of wasm; the green parse tree is
a host-side reconstruction (examples/web/parser.html). Matches native
event-for-event on a 46-input corpus and on JuliaSyntax's own parser.jl
under both wasmtime and V8.
Differential testing at every layer: WasmTools round-trips byte-stably and
is fuzzed against wasm-tools smith; WasmCodegen's harness runs every
corpus function natively and in wasmtime (values must isequal, Julia
exceptions must become traps/exceptions); examples/node_differential.jl
repeats the comparison on V8. Run a package's suite directly:
julia --project=. WasmCodegen/test/runtests.jl.
Wasmtime_jllis compat-pinned to v45, matching the ABI contracts verified inWasmtimeRunner/src/abi.jl;ENV["WASMTIME_LIB"]overrides.- Tests use the
wasm-toolsbinary if present attools/wasm-tools-dist/(release v1.251.0) and skip external validation otherwise;tools/also carries the wasmtime v45 C headers for ABI probes (seeCLAUDE.md).