crossbind
GitHub

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

crossbind.config.js
export default {
paths: {
config: import.meta.url,
},
};
Always set paths.config
Relative paths resolve from this file. Without it, a build started from another folder looks for your sources in the wrong place.

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 build mt (Threads and workers).
packages
What the project takes from outside npm: packages.cargo holds the crates cargo: imports (crate name and Cargo dependency spec), packages.conan the packages conan: imports. See Rust and Conan.
crossbind.config.js
import gdal from '@crossbind/port-gdal-wasm/crossbind.config.js';
 
export default {
general: { name: 'my-geo-app' },
dependencies: [gdal],
packages: {
cargo: { uuid: '{ version = "1", features = ["v4"] }' },
conan: { zlib: '1.3.2' },
},
paths: { config: import.meta.url },
};

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:

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

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.

crossbind.config.js
export default {
paths: { config: import.meta.url },
target: { runtime: 'mt' },
};

targetSpecs

Settings for some targets only. An entry applies when every field it sets (platform, arch, runtime, buildType, runtimeEnv) matches the target.

crossbind.config.js
targetSpecs: [
{
platform: 'wasm',
specs: {
cmake: { compileOptions: ['-DMYAPP_NO_LOGGING=1'] },
binary: { emccFlags: ['-sINITIAL_MEMORY=128MB'] },
env: { GDAL_NUM_THREADS: '0' },
data: { 'share/myapp': 'myapp/data' },
ignoreLibName: ['libtiff_legacy'],
},
},
]

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.

crossbind.config.js
export default {
paths: { config: import.meta.url },
target: { runtimeEnv: 'app' },
app: { name: 'My App', icon: 'icon.png' },
};

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'
crate
cargo only: the folder that holds Cargo.toml.
libName
The .a basenames 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 in Promise<...>, for worker runtimes.
Default'sync'
types
For package authors: writes one .d.ts over the public headers and sets up package.json, so imports of <pkg>/<any>.h get 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:

src/main.js
const m = await initNative({
useWorker: true,
fs: { opfs: true },
env: { TMPDIR: '_CROSSBIND_DATA_PATH_/scratch' },
});

Every option is in Runtime API. The ones that change behavior most: Threads and workers and Files.

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