crossbind
GitHub

Introduction

crossbind compiles C++ and Rust into WebAssembly, Node-API addons and native iOS and Android libraries, and hands them to JavaScript as an ordinary module. You import a header; the bindings are generated from it. The same sources also build into apps around a page of yours, and into executables that need no JavaScript.

No glue code, no second build system. Whatever the header declares (functions, classes, inheritance, overloads, vectors, maps, enums) shows up in JavaScript under the same names.

One import, no glue

Put your C++ in src/native and import the header from JavaScript. Call initNative() once; after it resolves, everything the header declares is callable. In a browser the module runs in a Web Worker by default, so calls return promises.

src/native/helloWorld.h
#pragma once
#include <string>
 
std::string getHelloWorldMessage() {
return "Hello World!";
}
src/main.js
import { initNative, getHelloWorldMessage } from './native/helloWorld.h';
 
await initNative();
console.log(await getHelloWorldMessage());

Rust works the same way: import a .rs file of the app, or a crates.io crate with cargo:. See Rust.

Libraries you do not have to build

16 C and C++ libraries ship prebuilt as @crossbind/port-*: GDAL, OpenSSL, SQLite, GEOS, PROJ and more, built from upstream sources at pinned versions. Install the variant for your platform and import its header; only your own code, the bindings and the final link are compiled.

src/main.js
import { initNative, GDALVersionInfo } from '@crossbind/port-gdal/gdal.h';
 
await initNative();
console.log(await GDALVersionInfo('RELEASE_NAME'));

One initNative() covers every header you import. More in crossbind ports; every library is listed under Libraries.

The same import reaches two registries: a Rust crate from crates.io with cargo:, and a C or C++ package from ConanCenter with conan:.

Where the output runs

PlatformWhat is produced
BrowserWebAssembly and a JavaScript loader, through your bundler
Node.jsWebAssembly, or a native Node-API addon
EdgeWebAssembly for Cloudflare Workers, or a wasi:http component
ElectronThe Node-API addon, loaded in the main process
AppsA macOS, Linux, Windows, iOS or Android app around your page
React NativeNative iOS and Android code over JSI, no wasm
ExecutablesNative programs for macOS, Linux and Windows, or a WASI command

Your JavaScript stays the same across these platforms; only the build target changes. Executables and wasi:http components run without a JavaScript host.

What ends up in your bundle

Only the code your imported headers reach is linked in: two functions of a large library cost those functions, not the whole library. Android is the exception: its builds link whole archives.

What you can tune: Performance and size.

Two ways to use it

  • Write C++ or Rust yourself. Your own sources in src/native, imported by header. Best when the work belongs on the native side: a whole pipeline in one call.
  • Call a prebuilt library from JavaScript. Import the package's header and call it. The quickest start.

Both use the same initNative() and mix freely in one project.

Why crossbind

Beneath the header import, crossbind distributes native libraries for JavaScript runtimes: versioned packages, binaries per target, their dependencies, build recipes and runtime adapters.

  • Target-aware distribution. One package family carries WebAssembly, iOS, Android, desktop and WASI variants, and each build takes only the one for its target.
  • Native dependency resolution. Packages declare their native dependencies, so they are built and linked in the right order.
  • A reproducible package contract. Port recipes pin upstream versions, source hashes and licenses.
  • No hand-written binding glue. Functions, classes, enums, containers and standard-library types bind from the header you already have.
  • C++ and Rust. Import your own sources, a cargo: crate or a native package the same way.
  • First-party integrations and ports. Bundler plugins rebuild only what changed, and prebuilt ports bring GDAL, SQLite, OpenSSL, GEOS, PROJ and more.

Limits worth knowing

  • Browser OPFS needs useWorker: true: browsers give synchronous file access only in workers.
  • Browser multithread builds (runtime: 'mt') need COOP/COEP headers in production. The thread pool has two workers by default; its size is configurable.
  • Edge runtimes such as Cloudflare Workers run single-threaded with an in-memory filesystem: no workers, no OPFS.
  • Android builds link whole archives: unused code is not dropped there.
  • iOS and macOS builds need Xcode on a Mac, and iOS also CocoaPods. Rust for those platforms needs a local cargo. WASI commands need wasmtime on PATH.
  • There is no performance claim: a hand-written loop in JIT JavaScript can match the same algorithm in Wasm. The value is the libraries you would otherwise rewrite.
  • crossbind 2.0 is in beta: prereleases carry no compatibility guarantee until the first stable release.

Every option and default is in Configuration, Runtime API and CLI.

Where to next

  • Quick start: from an empty folder to a running app.
  • Tutorial: short steps that run in your browser, with nothing to install.
  • C++: the rules your headers follow, and the type table.
  • Troubleshooting: the most common errors and their fixes.
Type to search every guide page and section.
↑↓ navigate↵ openesc close