StarlingMonkey

A SpiderMonkey-based JS runtime on WebAssembly

A Bytecode Alliance project

Building | Adopters | Documentation | Chat

StarlingMonkey is a SpiderMonkey based JS runtime optimized for use in WebAssembly Components. StarlingMonkey's core builtins target WASI 0.2.0 to support a Component Model based event loop and standards-compliant implementations of key web builtins, including the fetch API, WHATWG Streams, text encoding, and others. To support tailoring for specific use cases, it's designed to be highly modular, and can be readily extended with custom builtins and host APIs.

StarlingMonkey is used in production for Fastly's JS Compute platform, and Fermyon's Spin JS SDK. See the ADOPTERS file for more details.

Documentation

For comprehensive documentation, visit our Documentation Site.

Quick Start

Requirements

The runtime's build is managed by cmake, which also takes care of downloading the build dependencies. To properly manage the Rust toolchain, the build script expects rustup to be installed in the system.

Usage

With sufficiently new versions of cmake and rustup installed, the build process is as follows:

1. Clone the repo

git clone https://github.com/bytecodealliance/StarlingMonkey
cd StarlingMonkey

2. Run the configuration script

For a release configuration, run

cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release

For a debug configuration, run

cmake -S . -B cmake-build-debug -DCMAKE_BUILD_TYPE=Debug

3. Build the runtime

Building the runtime is done in two phases: first, cmake is used to build a raw version as a WebAssembly core module. Then, that module is turned into a WebAssembly Component using the componentize.sh script generated by the build.

The following command will build the starling-raw.wasm runtime module in the cmake-build-release directory:

# Use cmake-build-debug for the debug build
# Change the value for `--parallel` to match the number of CPU cores in your system
cmake --build cmake-build-release --parallel 8

Then, the starling-raw.wasm module can be turned into a component with the following command:

cd cmake-build-release
./componentize.sh -o starling.wasm

The resulting runtime can be used to load and evaluate JS code dynamically:

wasmtime -S http starling.wasm -e "console.log('hello world')"
# or, to load a file:
wasmtime -S http --dir . starling.wasm index.js

Alternatively, a JS file can be provided during componentization:

cd cmake-build-release
./componentize.sh index.js -o starling.wasm

This way, the JS file will be loaded during componentization, and the top-level code will be executed, and can e.g. register a handler for the fetch event to serve HTTP requests.