cross-code

An Nx monorepo for running WebAssembly on NativeScript — WASM runtime plugins built on a shared TypeScript foundation (wire protocol, adapter interfaces, base Runtime/Module/Function classes):

• wasm3 — lightweight interpreter (v0.5.2)
• WAMR — WebAssembly Micro Runtime (2.3.0): interpreter, Fast JIT, LLVM JIT, AOT, WASI
• WasmKit — Swift-based WebAssembly runtime with WASI support, iOS-native through SwiftPM
• WasmEdge — high-performance runtime (Swift Package on iOS, Kotlin + Rust JNI (cargo-ndk) on Android)
• Chicory — pure-Java interpreter, Android-only
• Endive — Java-native interpreter, Android-only

Also in the monorepo: ns-wry — a general-purpose NativeScript plugin scaffold built on Rust + UniFFI (uniffi-rs) auto-generated Kotlin/Swift bindings and cargo-ndk Android pipeline — and ns-rspack, an rspack bundler for NativeScript apps.

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

AI agents: start at AGENTS.md, then MEMORY.md. CLAUDE.md, GEMINI.md, CODEX.md, and .cursorrules point at those.

Packages

Package	Description
@cross-code/ns-wasm-core	Shared foundation — wire protocol, WasmError, adapter interfaces, base WasmRuntime/WasmModule/WasmFunction classes
@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-kit-runtime	NativeScript plugin — Swift Package on iOS (WasmKit interpreter); Android throws a clear unsupported error
@cross-code/ns-wasm-edge	NativeScript plugin — Swift Package on iOS, Kotlin + Rust JNI (cargo-ndk) on Android (WasmEdge runtime)
@cross-code/ns-wasm-chicory	NativeScript plugin — pure-Java Chicory interpreter on Android (no native toolchain needed)
@cross-code/ns-endive	NativeScript plugin — Java/JNI Endive interpreter on Android
@cross-code/ns-wasm-fixture	Rust/wasm-pack test fixtures (committed .wasm binaries)
@cross-code/ns-lynx	NativeScript plugin — embeds the LynxJS engine as a <LynxView>, rendering React on Lynx bundles inside a NativeScript page
@cross-code/ns-rstest	Rstest device test runner for NativeScript — Node host, Worker runtime, and optional on-device results page
@cross-code/ns-wry	NativeScript plugin — Rust + UniFFI (uniffi-rs) Kotlin/Swift bindings, cargo-ndk Android pipeline
@cross-code/ns-rspack	rspack bundler for NativeScript apps — the whole NativeScript build pipeline, natively on rspack
@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 Rstest + ns-rstest
ns-lynx-app	NativeScript host app for @cross-code/ns-lynx — a React on Lynx UI embedded beside native NativeScript views
rspack-test-app	NativeScript app bundled with @cross-code/ns-rspack (workspace member; installs with the root pnpm install)
ns-wry-app	NativeScript test app for @cross-code/ns-wry — WebView demo with google.com on iOS/Android

The WASM runtime plugins expose the same TypeScript API — see WASM.md. All runtime plugins (wasm3, WAMR, WasmKit, WasmEdge, Chicory, Endive) share the same foundation (@cross-code/ns-wasm-core) which provides the wire protocol, error classes, adapter interfaces and generic WasmRuntime/WasmModule/WasmFunction classes. 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

rspack-test-app is a workspace member, so the root pnpm install covers it.

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/download/latest/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.

rspack bundling

@cross-code/ns-rspack is an rspack bundler for NativeScript apps. It owns every NativeScript-specific rule — entry stubs, platform-suffixed resolution, XML/CSS loaders, copy rules, defines, HMR, the WatchStatePlugin IPC — natively, with no @nativescript/webpack and no webpack in its dependency tree. See packages/ns-rspack/README.md for usage and the differences table. Agent workflow: AGENTS.md, MEMORY.md.

The rspack-test-app exercises it end-to-end (bundler: 'rspack' in nativescript.config.ts); ns build ios / ns run ios (watch + HMR) run the bundler via the CLI bin and read build state over IPC. ns-lynx-app's device suite checks the bundle the app actually runs.

WebAssembly plugins (wasm3, WAMR, WasmKit, WasmEdge, Chicory & Endive)

Usage and API documentation for the 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.

All six plugins expose the same TypeScript API; only the class names differ (Wasm3Runtime / Wasm3Module / Wasm3Function vs WamrRuntime / WamrModule / WamrFunction vs WasmKitRuntime / WasmKitModule / WasmKitFunction, and the WasmEdge, Chicory and Endive equivalents). WasmKit is iOS-only (Swift-based runtime); Android throws a clear "not supported" error. Chicory and Endive are Java-based and Android-only.

Linting

Kotlin (Android wrappers)

# Detekt (static analysis) + Ktlint (formatting) — hand-written sources only
pnpm exec nx run ns-wasm3:lint.android
pnpm exec nx run ns-wasm3:lint.android --configuration=format  # auto-fix

# Config: detekt.yml + .editorconfig at the repo root (shared by both engines)

Swift (iOS wrappers)

# SwiftLint — hand-written sources only
pnpm exec nx run ns-wasm3:lint.ios
pnpm exec nx run ns-wamr:lint.ios

# Periphery — unused-code detection (builds the SwiftPM package)
pnpm exec nx run ns-wasm3:periphery.ios
pnpm exec nx run ns-wamr:periphery.ios

# Config: .swiftlint.yml + .periphery.yml at the repo root (shared by all engines)

Per-package documentation

Package	Docs
WebAssembly plugins (wasm3 & WAMR)	WASM.md — shared usage, API reference, marshalling, errors, troubleshooting
@cross-code/ns-wasm-core	AGENTS.md — wire protocol, WasmError, adapter interfaces, base classes
@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-kit-runtime	README — WasmKit Swift interpreter, iOS-only adapter, developing, troubleshooting
@cross-code/ns-wasm-edge	package — WasmEdge runtime, follows the Rust/UniFFI architecture of wasm3/wamr
@cross-code/ns-wasm-chicory	package — Chicory pure-Java interpreter, Android-only, byte marshalling
@cross-code/ns-endive	package — Endive Java interpreter, Android-only, developing, troubleshooting
@cross-code/ns-wasm-fixture	README — exported subpaths, rebuilding the .wasm fixtures
@cross-code/ns-lynx	README — why it needs no native layer, properties/events, producing a bundle
@cross-code/ns-rstest	README — Node host, Worker registry, concurrency, transport, and results UI
@cross-code/ns-wry	README — Rust + UniFFI architecture, platform stubs, developing, troubleshooting
@cross-code/ns-rspack	README — usage and webpack↔rspack gaps; AGENTS.md / MEMORY.md for agents
@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
rspack-test-app	rspack-bundled demo app (workspace member) — see packages/ns-rspack/README.md
ns-wry-app	README — WebView demo, build-plugin-and-run scripts, troubleshooting