cross-code

An Nx monorepo for running WebAssembly on NativeScript — three sibling plugins built on Rust + UniFFI:

• wasm3 — lightweight interpreter (v0.5.2)
• WAMR — WebAssembly Micro Runtime (2.3.0): interpreter, Fast JIT, LLVM JIT, AOT, WASI
• ns-wry — Rust + UniFFI (uniffi-rs) auto-generated Kotlin/Swift bindings, cargo-ndk Android pipeline

Project status: Active development. APIs and project layout may change without notice; expect breaking changes between releases.

Packages

Package	Description
@cross-code/ns-wasm3	NativeScript plugin — Swift Package on iOS, Kotlin + Rust JNI (cargo-ndk) on Android (wasm3 interpreter)
@cross-code/ns-wamr	NativeScript plugin — Swift Package on iOS, Kotlin + Rust JNI (cargo-ndk) on Android (WAMR: interpreter, Fast JIT, LLVM JIT, AOT, WASI)
@cross-code/ns-wasm-fixture	Rust/wasm-pack test fixtures (committed .wasm binaries)
@cross-code/vitest-ns	Vitest custom pool and NativeScript Worker runtime for on-device unit tests
@cross-code/vitest-ns-ui	Optional NativeScript Core results page for device-side Vitest progress
@cross-code/ns-wry	NativeScript plugin — Rust + UniFFI (uniffi-rs) Kotlin/Swift bindings, cargo-ndk Android pipeline
@cross-code/nx-buck2	Nx plugin for Buck2 native builds — debug/release profiles, cross-compilation, size optimization
ns-wasm-test	NativeScript test app — runs the plugins on a simulator/emulator from a demo page and through Vitest + vitest-ns
ns-wry-app	NativeScript test app for @cross-code/ns-wry — WebView demo with google.com on iOS/Android

Both plugins expose the same TypeScript API — see WASM.md. Each package README covers its own layout, development workflow and troubleshooting (see Per-package documentation).

Prerequisites

• Node 22.13+, pnpm (the default package manager — packageManager in package.json)
• Runtime versions are pinned with mise (.mise.toml: node 24.18.1, java temurin-21.0.2, pnpm 11.20.0)
• iOS: Xcode + Swift toolchain (for swift test)
• Android: JDK 17+, Android SDK with NDK 29 (ANDROID_HOME set)
• Buck2 (optional): only for the nx-buck2 native-build targets — see Buck2 builds

Getting started

pnpm install

The NativeScript test app is not a workspace member (the ns CLI needs its own node_modules) — it has its own pnpm-workspace.yaml and lockfile. Before running its suite, install it separately:

cd apps/ns-wasm-test && pnpm install

Run TypeScript build and unit tests (no native toolchain required):

pnpm exec nx run-many -t build test

Clean all build caches and generated artifacts (incl. dist, .buck-out, test-output, Gradle/Rust targets, nx-buck2 compiled JS):

node tools/clean.mjs        # build artifacts only
node tools/clean.mjs --all  # also remove node_modules trees

Running tests

# Vitest unit tests + typecheck (no native toolchain, no device)
pnpm exec nx run-many -t test typecheck

# iOS XCTests (runs wasm3 / WAMR natively on macOS)
pnpm --filter ./packages/ns-wasm3 run test.ios
pnpm --filter ./packages/ns-wamr run test.ios

# Android JVM host tests (no emulator needed)
pnpm --filter ./packages/ns-wasm3 run test.android
pnpm --filter ./packages/ns-wamr run test.android

# The test app's Vitest suite, on a simulator / emulator
pnpm exec nx run ns-wasm-test:test.ios
pnpm exec nx run ns-wasm-test:test.android

# On-device Istanbul coverage reports
pnpm exec nx run ns-wasm-test:test.ios.coverage
pnpm exec nx run ns-wasm-test:test.android.coverage

On macOS, NativeScript's iOS build needs a UTF-8 locale (export LANG=en_US.UTF-8) — otherwise the CLI's CocoaPods check fails before the build starts.

wamr native suites need the vendored WAMR C sources (packages/ns-wamr/src/vendors/wamr/, WAMR-2.3.0). If the source tree is ever missing, the wamr native commands and CI jobs (wamr-ios, wamr-android) skip gracefully — they print a SKIP: message and exit 0 rather than fail. The TypeScript layer and vitest specs run normally.

Nx tasks

# Build a single project
pnpm exec nx run ns-wasm3:build
pnpm exec nx run ns-wamr:build

# Run all affected tasks
pnpm exec nx affected -t build test

# Visualise the project graph
pnpm exec nx graph

Buck2 builds

Native builds can optionally run through Buck2 via the @cross-code/nx-buck2 plugin — debug/release profiles, per-platform cross-compilation, size optimization, and symbol preservation:

# Release build (default: -Oz, LTO, stripped)
nx run ns-wamr:buck2-build --configuration=release

# Debug build (-O0 -g3, full DWARF)
nx run ns-wamr:buck2-build --configuration=debug

# Cross-compile for a platform/arch
nx run ns-wamr:buck2-build --platform=ios --arch=arm64

# All native projects at once
nx run-many -t buck2-build -p ns-wamr ns-wasm3 ns-wry

Install Buck2 once (it is not on crates.io — the buck2 crate is a placeholder):

curl -fsSL https://github.com/facebook/buck2/releases/latest/download/buck2-aarch64-apple-darwin.zst \
  | zstd -d | sudo tee /usr/local/bin/buck2 > /dev/null && sudo chmod +x /usr/local/bin/buck2

or mise plugin install buck2 https://github.com/izaakschroeder/asdf-buck2.

WebAssembly plugins (wasm3 & WAMR)

Usage and API documentation for the two WebAssembly plugins — install, quick start, calling exports, linear memory, globals, host imports, value marshalling, error messages, the complete API reference, and shared troubleshooting — lives in WASM.md.

Both plugins expose the same TypeScript API; only the class names differ (Wasm3Runtime / Wasm3Module / Wasm3Function vs WamrRuntime / WamrModule / WamrFunction).

Per-package documentation

Package	Docs
WebAssembly plugins (wasm3 & WAMR)	WASM.md — shared usage, API reference, marshalling, errors, troubleshooting
@cross-code/ns-wasm3	README — platform details, package layout, developing, troubleshooting, license
@cross-code/ns-wamr	README — execution tiers, package layout, developing, troubleshooting, license
@cross-code/ns-wasm-fixture	README — exported subpaths, rebuilding the .wasm fixtures
@cross-code/vitest-ns	README — custom pool, Worker registry, concurrency, and transport
@cross-code/vitest-ns-ui	README — optional NativeScript results UI
@cross-code/ns-wry	README — Rust + UniFFI architecture, platform stubs, developing, troubleshooting
@cross-code/nx-buck2	README — Buck2 executors/generators, CLI usage
ns-wasm-test	README — running the demo page and the on-device Vitest suite, troubleshooting
ns-wry-app	README — WebView demo, build-plugin-and-run scripts, troubleshooting