Configuration
crossbind.config.js sits at your project root and configures the build. Runtime options go to initNative(opts) instead. Most projects need only the lines below.
The minimum
Identity and dependencies
general.name- Names the output (
lib<name>.a) and the browser folder/opfs/<name>/. - Defaultyour package name
dependencies- Other packages' configs, each imported from a platform variant such as
@crossbind/port-*-wasm/crossbind.config.js, one per platform you build. Their own dependencies come along, and a multithreaded one makes your buildmt(Threads and workers).
Paths
config- Always
import.meta.url. project- The project root.
- Defaultthe folder of
config base- A root above the project, for a monorepo (see below).
native- The C++ source roots, an array. Their order sets include precedence.
- Default
['src/native'] cache- The build cache.
- Default
.crossbind build- The staging folder.
- Default
.crossbind/build output- Where the built files go.
- Defaultthe same as
build header,module,bridge,cmake- Set them only when your layout differs.
- Defaultderived from
native
Docker sees nothing above the project folder. In a monorepo, point base at the repository root:
Target
target narrows what gets built. Most projects set only runtime: 'st' (the default) or 'mt'. mt asks more of the host; see Threads and workers.
targetSpecs
Settings for some targets only. An entry applies when every field it sets (platform, arch, runtime, buildType, runtimeEnv) matches the target.
Its most common use, shipping data files, has its own page: Data files.
App
app describes an app (target: { runtimeEnv: 'app' }): its name, id, icon and window, the links that open it, the reasons it gives for devices, and its updates. Apps lists every key. extensions lists the app's extensions, each from its package's crossbind.extension.js.
Export
export matters only when you publish a package: it describes what its users receive.
type'cmake'for C and C++, or'cargo'for a Rust crate built per platform.- Default
'cmake' cratecargoonly: the folder that holdsCargo.toml.libName- The
.abasenames the build makes, one per entry. header,libPath- The include and library folder names inside
dist. bindings.vectors- Extra
Vec<T>classes to expose without touching the Rust source. wholeArchive- Links every archive whole instead of dropping unused code. Use it only when members register themselves from static initializers.
TypeScript output
dts'promise'wraps every generated return type inPromise<...>, for worker runtimes.- Default
'sync' types- For package authors: writes one
.d.tsover the public headers and sets uppackage.json, so imports of<pkg>/<any>.hget types.
The rest
ext- Which file extensions count as headers, sources and SWIG modules.
build- Do not set it here: build hooks live in
crossbind.build.js, which is merged in. functions.isEnabled- Overrides the check whether a target is enabled, which by default asks whether its output exists.
Machine settings (runner, Xcode team, local wasi-sdk) live in ~/.crossbind.json, never in the project config. When more than one layer can change a setting, use the highest one: see the override hierarchy.
Not in this file: runtime options
useWorker: true in crossbind.config.js does nothing. Runtime options go to initNative:
Every option is in Runtime API. The ones that change behavior most: Threads and workers and Files.