Javy Documentation

Javy is composed of several crates that work together to compile JavaScript to WebAssembly (Wasm) and provide a QuickJS-based runtime. The core workflow involves the javy-cli driving javy-codegen to produce Wasm modules. The runtime itself is powered by the javy crate, which is designed to compile to wasm32-wasip1 or wasm32-wasip2 and provides APIs for configuring a QuickJS environment.

Core Component Relationships:

• javy-cli $\rightarrow$ javy-codegen $\rightarrow$ wasm (the resulting module)
• javy-plugin $\rightarrow$ javy-plugin-api $\rightarrow$ javy $\rightarrow$ rquickjs (the runtime engine)

Key Crates:

• javy: The primary library entrypoint for third parties to configure a QuickJS-based runtime.
• javy-cli: The command-line interface used to compile JS to Wasm.
• javy-codegen: The Rust crate responsible for the actual JS-to-Wasm compilation.
• javy-plugin: The default plugin (compiled to plugin.wasm) used by the CLI and dynamic environments. It defines an initialize_runtime function.
• javy-plugin-api: Provides common implementations for exports (like the invoke function) and custom Wasm sections required by plugins.

WASI preview 2 plugins use Wasm components and require a WIT file to define the interface.

Steps:

1. Configure Cargo.toml with javy-plugin-api = "5.0.0" and wit-bindgen = "0.47.0".
2. Create a wit/world.wit file defining your exports (e.g., compile-src, initialize-runtime, invoke) and any necessary imports.
3. Use the javy_plugin! macro in src/lib.rs to implement the plugin logic, or implement the Guest trait directly if avoiding the macro.
4. Build using cargo build --target=wasm32-wasip2 --release.
5. Initialize the plugin for the Javy CLI using:

   javy init-plugin <path_to_plugin> -o <path_to_initialized_module>

Note: Because components are converted to modules, parameter and result types are lowered to core Wasm equivalents. Use cabi_realloc for structured data like strings or arrays.

[package]
name = "my-plugin-name"
version = "0.1.0"

[lib]
name = "my_plugin_name"
crate-type = ["cdylib"]

[dependencies]
javy-plugin-api = "5.0.0"
wit-bindgen = "0.47.0"

package yournamespace:my-javy-plugin@1.0.0;

world my-javy-plugin {
    export compile-src: func(src: list<u8>) -> result<list<u8>, string>;
    export initialize-runtime: func();
    export invoke: func(bytecode: list<u8>, function: option<string>);
}

use javy_plugin_api::{
    javy::{quickjs::prelude::Func, Runtime},
    javy_plugin,
    Config,
};

wit_bindgen::generate!({ world: "my-javy-plugin", generate_all });

fn config() -> Config {
    Config::default()
}

fn modify_runtime(runtime: Runtime) -> Runtime {
    runtime.context().with(|ctx| {
        // Creates a `plugin` variable on the global set to `true`.
        ctx.globals().set("plugin", true).unwrap();
        ctx.globals()
            .set(
                "func",
                Func::from(|| {
                    crate::imported_function();
                }),
            )
            .unwrap();
    });
    runtime
}

struct Component;

// Set your plugin's import namespace.
javy_plugin!("my-javy-plugin", Component, config, modify_runtime);

export!(Component);

Javy is a configurable JavaScript runtime for WebAssembly that uses QuickJS via the rquickjs crate. It allows you to evaluate either JavaScript source code or QuickJS bytecode within a Rust environment.

To use Javy, initialize a Runtime, create a context, and use the context.with method to interact with the JavaScript global scope. You can define Rust functions as JavaScript functions using Function::new and MutFn to expose them to the JS environment.

use anyhow::Result;
use javy::quickjs::{
   function::{MutFn, Rest},
   Ctx, Function, Value
};
use javy::{from_js_error, Runtime};

fn main() -> Result<()> {
    let runtime = Runtime::default();
    let context = runtime.context();

    context.with(|cx| {
        let globals = cx.globals();
        globals.set(
            "print_hello",
            Function::new(
                cx.clone(),
                MutFn::new(|_: Ctx<'_>, _: Rest<Value<'_>>| {
                    println!("Hello, world!");
                }),
            )?,
        )
    })?;

    context.with(|cx| {
        cx.eval_with_options("print_hello();", Default::default())
            .map_err(|e| from_js_error(cx.clone(), e))
            .map(|_: ()| ())
    })?;

    Ok(())
}