WASI

Run WebAssembly command and reactor modules with WASI preview1.

wasi_snapshot_preview1 for WebAssembly modules, shaped like Node’s node:wasi. WebAssembly itself is the standard global (MDN).

import { WASI } from "@native/wasi";

Nothing is patched globally. Create a WASI, pass its imports to WebAssembly.instantiate, then start() a command or initialize() a reactor.

---

WASI

constructor

new WASI(options?: WASIOptions)

Creates one WASI environment.

Option	Default
args	[]	argv, including argv[0]
env	{}	environment variables
preopens	{ "/": data/ }	guest directory → host directory; relative host paths start at data/
returnOnExit	true	proc_exit(code) ends start(), which returns code; false makes it throw instead
version	"preview1"	the only one

A host directory outside data/ needs the filesystem permission and must exist.

const wasi = new WASI({
    args: ["app", "--fast"],
    env: { MODE: "demo" },
    preopens: { "/": ".", "/assets": "assets" },
});

getImportObject

wasi.getImportObject(): { wasi_snapshot_preview1: Readonly<Record<string, WasiSyscall>> }

The imports to pass to WebAssembly.instantiate. wasi.wasiImport is the same syscall table on its own, for merging with your own imports.

const { instance } = await WebAssembly.instantiate(bytes, wasi.getImportObject());

const imports = { wasi_snapshot_preview1: wasi.wasiImport, env: { log: (n: number) => console.log(n) } };

start

wasi.start(instance: WebAssembly.Instance): number

Runs a command: calls _start() and returns the exit code (0 when _start returns). Call start() or initialize() once per WASI.

const code = wasi.start(instance);

With returnOnExit: false, proc_exit throws an Error with exitCode.

initialize

wasi.initialize(instance: WebAssembly.Instance): void

Sets up a reactor (a module without _start): calls _initialize() if it’s exported. Then call its exports yourself.

wasi.initialize(instance);
const add = instance.exports.add as (a: number, b: number) => number;
add(2, 3);

dispose

wasi.dispose(): void

Closes every file the guest opened. Happens on unload anyway. alive is false afterwards, and using disposes at the end of the block.

---

Guest environment

argv / environ	exactly args / env
Filesystem	only the preopens, no .. out of them
stdin	empty
stdout / stderr	the script log, stderr as errors
sleep()	returns immediately
Sockets	none

---

Example

Run a WASI command from data/app.wasm.

import { WASI } from "@native/wasi";
import fs from "@native/fs";

async function runApp(args: string[]): Promise<number> {
    using wasi = new WASI({ args: ["app", ...args], env: { MODE: "demo" } });
    const bytes = await fs.readFile("app.wasm");
    const { instance } = await WebAssembly.instantiate(bytes, wasi.getImportObject());
    return wasi.start(instance);
}

const code = await runApp(["--fast"]);
console.log("exit", code);