crossbind
GitHub

Rust

Rust binds the way a C++ header does: structs, impl blocks and pub fns become classes and functions, with no macros or glue to write. Write the file next to your other native sources and import it.

Setup

With the default Docker runner, builds for the web, Android, Linux and Windows need no Rust on your machine: cargo runs in the toolchain image. iOS and macOS builds run cargo on your Mac, as every build does under RUNNER=LOCAL, so those need cargo and the platform targets. Unchanged code does not rebuild.

The binding layer is one dev dependency. The Vite, Rollup, Webpack and React Native plugins already bring it, so most projects have it:

shell
npm install -D @crossbind/core-embind-rust
Two limits
platform: 'wasi' skips Rust: there is no wasm32-wasip3 Rust target yet. And under RUNNER=LOCAL, the wasm mt runtime needs a std built with atomics: with the pinned rustc, crossbind downloads one; with any other, it rebuilds std on nightly, which needs rustup toolchain install nightly --component rust-src once.

Import a .rs file

Write Rust next to your C++ in src/native and import the file like a header:

src/native/counter.rs
pub struct Counter {
total: i32,
}
 
impl Counter {
pub fn new(start: i32) -> Self {
Counter { total: start }
}
pub fn add(&mut self, n: i32) -> i32 {
self.total += n;
self.total
}
pub fn total(&self) -> i32 {
self.total
}
}
src/main.js
import { initNative, Counter } from './native/counter.rs';
 
await initNative();
 
const counter = await new Counter(40);
console.log(await counter.add(2));

The bridge reads that file's public items. Crates the file uses go in packages.cargo in crossbind.config.js, the same map that lets you import a crate directly (crates.io):

crossbind.config.js
export default {
packages: {
cargo: {
geo: '0.29',
wkt: '0.11',
},
},
paths: { config: import.meta.url },
};

What plain Rust maps to

RustJavaScript
struct + impl methodsclass with methods (Type::new becomes the constructor)
&str / &String parameters, String returnsstrings
i32 / f64 / boolnumber / boolean
i64 / u64BigInt, both directions
Option<T>null / undefined ↔ None
Result<T, E> returnsthrows an Error on Err
impl DisplaytoString()
free pub fnplain exported function
&OtherClass parameterspass the other class's instance
serde_json::Valuereal JS values, deep-copied at the boundary
Arc<Class>shared ownership across several JS handles
embind_rs::JsValue / JsFunctionlive JS values by identity, and callbacks into JS

Slices, collections, serde types and std::io streams are in the full table. A function the bridge cannot carry, such as one with more than six parameters (seven for new), is left out.

JsValue and JsFunction need a synchronous runtime
They work on React Native, in a Node.js addon, and in wasm st on the page thread (useWorker: false in a browser). Behind a worker, the browser default, use serde_json::Value: functions cannot cross and identity is lost.

A panic reaches JavaScript as an Error with the panic message. Treat it as a crash: on wasm the instance is unusable afterwards, so start a fresh module. A wasm build that links Rust gets a 1 MiB stack instead of Emscripten's 64 KiB; for more, set -sSTACK_SIZE in targetSpecs binary.emccFlags.

To ship Rust for other projects to install, publish the crate as a package: see Publishing packages.

TypeScript

A .rs import is typed like a header, through @crossbind/typescript-config; set it up as in Runtime API.

Type to search every guide page and section.
↑↓ navigate↵ openesc close