crossbind
GitHub

Quick start

Scaffold a new project, or add crossbind to an app you already have. Either way you end up with a bundler plugin, a crossbind.config.js and a header you import from JavaScript.

Rather try it first?
The tutorial runs in your browser with nothing to install: nine short steps from a first function to Rust and packages.

Prerequisites

The toolchains come as Docker images, so you need little on your machine:

  • Docker, for the WebAssembly, WASI and Android toolchains. The first build pulls the images. Without Docker, Remote builds run them on another machine.
  • Node.js 24+.
  • CMake 3.28+, for mobile only.
  • Xcode and CocoaPods, for iOS only, on a Mac. Xcode must find Node.js; see React Native.
  • A Rust toolchain (cargo and the platform targets), only for Rust on iOS or macOS, or with RUNNER=LOCAL. Other builds run cargo in the image. See Rust.
  • wasmtime, only to run WASI output and the prebuilt -standalone-wasi tools.
shell
docker --version
node --version
docker pull ghcr.io/crossbind/web:1.0.21 # optional: the first build pulls it anyway

Set it up with a coding agent

Using a coding agent such as Claude Code, Codex, Cursor or Copilot? Paste this line into it. The agent installs the crossbind skill, adds crossbind to the project and checks one call from JavaScript, following these instructions.

prompt
Fetch and follow the instructions at https://crossbind.dev/agent/prompt.md to add crossbind to this project.

Prefer to do it yourself? Keep going.

A new project

The scaffolder sets up the bundler, its plugin and a starter crossbind.config.js. Answer the prompts; if unsure, pick Web, React and Vite. For a desktop or mobile app, pick Desktop and App, then follow Apps.

shell
npm create crossbind@beta
shell
? Project name › my-app
? Where should we create your project? › ./my-app
? What kind of project? › Web
? Choose framework / variant › React
? Choose bundler / ecosystem › Vite

Arguments answer the prompts in order, for CI and scripts:

shell
npm create crossbind@beta my-app Web React Vite

Then install, start the dev server, and skip to your first call.

shell
cd my-app
npm install
npm run dev

An existing project

Install the plugin for your bundler and register it. Vite is shown here; Webpack, Rspack and Rollup are on Bundler plugins, Metro on React Native.

shell
npm install -D @crossbind/plugin-vite@beta
Versions on this page
Install commands here follow the npm beta tag. When this page was built, that meant [email protected] (changelog), @crossbind/[email protected] (for crossbind ^2.0.0-beta.76) and [email protected]. To set up the same versions later, pin them:
shell
npm create crossbind@2.0.0-beta.78 my-app Web React Vite
npm install -D @crossbind/plugin-vite@2.0.0-beta.76 crossbind@2.0.0-beta.78
vite.config.js
import { defineConfig } from 'vite';
import viteCrossbindPlugin from '@crossbind/plugin-vite';
 
export default defineConfig({
plugins: [viteCrossbindPlugin()],
});

The plugin reads crossbind.config.js from your project root. The minimal one sets paths.config, which every other path resolves from:

crossbind.config.js
export default {
paths: {
config: import.meta.url,
},
};

Everything else it takes: Configuration.

Your first call

C++ lives in src/native. Declare the class in a header: the binder reads only headers.

src/native/MySampleClass.h
#pragma once
#include <string>
 
class MySampleClass {
public:
static std::string sample() {
return "Hello World!";
}
};

Import the header from your app and call it. The header module exports initNative(); one call starts every native module you imported. In a browser the module runs in a Web Worker by default, so each call returns a promise.

src/main.js
import { initNative, MySampleClass } from './native/MySampleClass.h';
 
await initNative();
console.log(await MySampleClass.sample());
First build
The first npm run dev compiles in Docker and takes a while. Later builds reuse the cache, and editing the header reloads the page.

Build for production

Your bundler's build compiles a release build through the plugin.

shell
npm run build

Building for another platform? Each one has its own page: Node.js, Edge, Electron, Apps, React Native and Executables.

Where to next

  • C++: what binds, and the C++ and JavaScript types.
  • crossbind ports: use a prebuilt library instead of compiling one.
  • Files: where files live in the browser, in Node.js and on the edge.
  • Troubleshooting: when the first build fails.
Type to search every guide page and section.
↑↓ navigate↵ openesc close