package js_of_ocaml

Wasm_of_ocaml

Wasm_of_ocaml is an alternative compiler which compiles OCaml bytecode to WebAssembly.

Supported engines

The generated code works with Chrome 119, Node.js 22, Firefox 122, and Safari 18.2 (or more recent versions of these applications).

In particular, the output code requires the following Wasm extensions to run:

• the GC extension, including functional references and 31-bit integers
• the tail-call extension
• the exception handling extension

OCaml 5.x code using effect handlers can be compiled in three different ways:

• --effects=jspi (default) emits code utilizing the JavaScript-Promise Integration extension. It works by default in Chrome 137, Node.js 25, and higher versions. Performing effects is slower than with --effects=cps.
• --effects=cps enables the CPS transformation from js_of_ocaml. The generated code is slower, larger, and less readable, but it runs on any supported engine. Use this for other browsers.
• --effects=native uses the WebAssembly Stack Switching proposal (typed continuations). It provides the best performance but requires a runtime with support for the WasmFX extension (currently available, behind the --experimental-wasm-wasmfx flag, in Chrome 148 or higher, or in a recent Node.js canary release with V8 version 14.7.100 or higher).

Installation and usage

Installation and usage documentation can be found in the js_of_ocaml manual.

Running the test suite

The following commands can be used to set up an opam switch and run the test suite. A recent Node.js and Binaryen need to be available on the PATH.

opam switch create wasm-tests 5.3.0
eval $(opam env --switch=wasm-tests)
opam pin add -y -n --with-version 6.4.1 .
opam install . --deps-only --with-test
WASM_OF_OCAML=true dune build @runtest-wasm

Compatibility with Js_of_ocaml

Since the value representation is different, some adaptations are necessary.

The most notable change is that, except for integers, OCaml numbers are no longer mapped to JavaScript numbers. So, explicit conversions Js.to_float and Js.float are now necessary to convert between OCaml floats and JavaScript numbers. The typing of JavaScript Typed Arrays has also been changed to deal with this.