Cairo Runner WASM

A Cairo runner compiled to WebAssembly, usable from JavaScript (Node, browser, Deno). It mirrors the api crate's /run and /test endpoints: send Cairo source code, get back a JSON response with the run output or test results.

Usage

import { init, run, test } from "cairo-runner";

await init();

const res = await run("fn main() -> felt252 { 0x25 }");
console.log(res.message);
// Run completed successfully, returning [37]

const tests = await test(`
  #[test]
  fn test_pass() { assert(true, 'should pass'); }
`);
console.log(tests.message);
// running 1 test
// test lib::test_pass ... ok

API

• init(options?): Promise<void> — loads the bundled wasm (idempotent); a compiled module, bytes, file path, or URL can be supplied for custom hosts.
• run(code: string): Promise<CairoRunResponse> — direct equivalent of /run.
• test(code: string): Promise<CairoRunResponse> — direct equivalent of /test.
• runCairo(code: string, options?: { test?: boolean }): Promise<CairoRunResponse> and runCairoTests(code) — compatibility aliases.
• CairoRunResponse — { message: string, success: boolean }.

Changelog

See CHANGELOG.md for release history.

Building the wasm

Requires a Rust toolchain with the wasm32-unknown-unknown target:

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.125 --locked
cargo build -p cairo-runner-wasm --target wasm32-unknown-unknown --release
pnpm build  # generates wasm-bindgen glue + embedded base64 wasm, compiles TypeScript into dist/

Publishing

Requires an npm account logged in locally (npm login) with publish access to the cairo-runner package.

Prerequisites

• Rust toolchain with the wasm32-unknown-unknown target (see Building the wasm).
• wasm-bindgen-cli 0.2.125 installed.
• Node.js 18+ and pnpm.

Release checklist

cd npm
pnpm build          # rebuild wasm glue + TypeScript into dist/
pnpm test           # run the test suite against the built wasm
npm pack --dry-run  # inspect the tarball contents and size

Verify the dry-run output shows exactly the expected files: dist/* (JS, .d.ts, sourcemaps), README.md, LICENSE, package.json. The wasm is embedded as base64 inside the JS bundle (large, ~27 MB of source text) because it embeds the corelib — this is expected.

Publish

npm publish         # publishes the current version from package.json

Updating the version

Bump the version first, then publish:

npm version patch   # or minor / major
npm publish

Each publish must have a unique version — npm rejects duplicate versions.

Smoke-test after publishing

mkdir -p /tmp/cairo-smoke && cd /tmp/cairo-smoke
npm init -y
npm install cairo-runner
node -e "import('cairo-runner').then(async m => { await m.init(); const r = await m.run('fn main() -> felt252 { 0x25 }'); console.log(r.message); })"

You should see Run completed successfully, returning [37].

The wasm is embedded as base64 in the JS bundle and loaded from an in-memory data: URL, so no .wasm file ships with the package.