C++
There are no binding macros to write: the generator reads your header and writes the bridge. It handles a subset of C++. Inside it everything binds; outside it, wrap the API in something that does.
The rules
The public surface belongs in the header
The binder reads only headers: a class defined only in the .cpp, an anonymous namespace around the API or a file-scope static function is invisible to it. Public members bind; private ones do not.
Single inheritance only
Single-base virtual polymorphism works. Multiple inheritance, diamonds especially, breaks the binder: use composition or a wrapper.
Templates need explicit instantiation
Fields are properties
Public fields of numbers, bool and std::string, in a class or a C struct, read and write as properties. Fields of vector, shared_ptr or class type need accessor methods, and arrays are not bound.
std::unique_ptr returned across the boundary fails silently: the call returns null or undefined. Use std::shared_ptr for anything JavaScript holds.Primitive types
| C++ | JavaScript | Note |
|---|---|---|
void | undefined | |
bool | true / false | |
char, short, int and unsigned forms | Number | a char parameter also takes a one-character string |
float, double | Number | |
int64_t, uint64_t, long long | BigInt | takes a BigInt or a safe-integer Number |
long, size_t | Number on wasm32, BigInt on React Native | |
std::string | String | |
const char * | String | see pointers |
std::optional<T> | the value or null | C++17, every runtime |
emscripten::val | anything | the untyped escape hatch |
An argument of the wrong type throws a TypeError instead of crossing as 0. An enum parameter takes a member of the enum or its number.
Vectors, maps and enums
Vectors bind under generated names: VectorInt, VectorDouble, VectorString, VectorInt64 and so on. std::vector<MyClass> becomes VectorMyClass.
To work with plain arrays, convert with two module helpers:
Maps bind the same way (MapIntInt, MapStringString, MapStringInt, MapIntString). Enums, enum and enum class alike, arrive as objects keyed by their member names.
std::vector arrives as a plain array instead of a vector. m.toArray() takes both, so code that uses it works either way.Pointers
Raw pointers bind. What cannot become an object crosses as a handle: an opaque NativePointer that holds the address and owns what crossbind allocated for it.
| C++ | JavaScript |
|---|---|
const char * parameter | a string, a handle or null |
const char * return | a string or null |
char *, void *, T **, pointers to numbers | a handle |
T * to a class or struct the header binds | an instance |
T * to a type the header only declares (sqlite3, PJ) | a handle |
int &, double &, std::string & out-parameters | a handle from allocPointer or allocString, read back afterwards |
| function pointer | a JavaScript function, a handle or null |
Every module that binds a pointer also exports helpers to make and read handles: cstring and readCString, allocBuffer and allocPointer (zero-filled), allocString and readString, readNumberAt and writeNumberAt, readPointerAt and writePointerAt, readBuffer (a Uint8Array copy) and writeBuffer, and releaseCallback.
Only const char * converts to a string. A char * result is memory the library hands over: it stays a handle you read and then free the library's way. A string passed for a const char * lives only for the call; if C keeps the pointer, pass a cstring handle and keep it until C is done.
A JavaScript function passed for a function pointer holds a slot in the module until releaseCallback(fn) frees it. With useWorker: true, handles are proxies and JavaScript functions cannot cross into the worker.
Constants and macros
A #define with a number, character, string or boolean value, and a const or constexpr global of those types, bind as module constants. Only the names you import bind, so thousands of macros cost nothing until you use one:
A function-like macro that calls one bound function, a macro that renames one, a variadic function and a mutable global bind as well, but only when you name them in an import { ... }; import * as reaches none of them. Details: cpp-binding-rules.md.
What a library header binds
Your own headers bind every function and class. A dependency's header (a port or a ConanCenter package) binds its enums, the functions you import and the classes they reach, with their bases. What nothing you import reaches is left out, and so is the library code only it uses.
import * as, import(), require, a bare import 'x.h' and an import of initNative alone bind the whole header. Otherwise a function you call through the module object (m.GDALVersionInfo()) still needs a named import; without one the call fails with m.GDALVersionInfo is not a function. Dev servers bind a newly imported function when you save the file.
Exceptions
Report a failure by throwing in C++ and catching in JavaScript, rather than with status codes or out-parameters.
On wasm the message is "<type>: <what()>", with the halves also available as e.cppType and e.cppMessage. On React Native (JSI) and in a Node-API addon it is the plain what() text.
Memory
A handle frees only what crossbind allocated for it. When objects are freed, and when to call .delete(): Object lifetime.
Wrapping what does not fit
For a library full of templates, multiple inheritance or pointer-heavy calls, put a clean class in front of it. The wrapper binds; the upstream type stays inside it.
An app keeps its wrappers in src/native. A published package carries its own, so everyone who installs it gets them.
TypeScript
Types for every header and Rust import are generated under .crossbind/. Setting them up, and dts: 'promise' for worker mode: Runtime API.
The escape hatch
When neither the rules nor a wrapper fit, hand-write a SWIG interface file next to the header and import it from JavaScript. It is also how you register a container the generator does not cover: