crossbind-config

<!-- GENERATED from docs/api/crossbind-config.md by scripts/build-agent-skill.mjs. Do not edit. -->

`crossbind.config.js` — Build-time Configuration

> **Build-time only.** Read once by the `crossbind build` CLI. NOT consumed at runtime. Runtime configuration lives in [`init.md`](./init.md).

Every consumer (app or library) writes a `crossbind.config.js` at the project root. It declares dependencies, source paths, build target, and export shape — everything the CLI needs to compile and package your C++.

Shape

export default {
  // ─────────────────────────────────────────────────────────────
  // General identity
  // ─────────────────────────────────────────────────────────────
  general: {
    name: 'myapp',
      // Logical app/lib name. Used for:
      //   - Output binary names (lib<name>.a, <name>.xcframework)
      //   - Browser fs namespace: /opfs/<name>/, /memfs/<name>/
      // Defaults to fixPackageName(package.json.name) or 'crossbindsample'.
  },

  // ─────────────────────────────────────────────────────────────
  // Other crossbind packages this project depends on
  // ─────────────────────────────────────────────────────────────
  dependencies: [],
    // Array of crossbind.config.js values, imported from platform variants such as
    // @crossbind/port-*-wasm, -android, -ios, -darwin, -linux, -linuxmusl, -win32 or -wasi. The meta package
    // (@crossbind/port-*) carries no config; list one variant per platform you build.
    // Example:
    //   import gdal from '@crossbind/port-gdal-wasm/crossbind.config.js'
    //   dependencies: [gdal]
    //
    // Transitive deps are automatically flattened into config.allDependencies.
    // If ANY dep declares target.runtime === 'mt', this project auto-promotes
    // to 'mt' too.

  // ─────────────────────────────────────────────────────────────
  // Rust crates this project consumes (the cargo store axis)
  // ─────────────────────────────────────────────────────────────
  cargoDependencies: {
    uuid: '{ version = "1", features = ["v4"] }',
    semver: '1',
  },
    // Crates importable via the `cargo:` scheme (`import { Uuid } from 'cargo:uuid'`,
    // or one public module: 'cargo:xxhash-rust/xxh3') or used by app-local .rs
    // sources. Keys are crate names, values are Cargo.toml dependency specs as
    // strings. Undeclared `cargo:` imports are a hard error. See rust.md.

  // ─────────────────────────────────────────────────────────────
  // C and C++ packages this project takes from ConanCenter
  // ─────────────────────────────────────────────────────────────
  conanDependencies: {
    zlib: '1.3.2',
    sqlite3: { version: '3.53.4', options: { enable_fts5: true } },
  },
    // Packages whose headers are importable via the `conan:` scheme
    // (`import { zlibVersion } from 'conan:zlib/zlib.h'`) and usable from your
    // own headers. Keys are Conan package names; values are a version, a Conan
    // range ('[>=1.3 <2]') or { version, options }. Web builds only for now.
    // Undeclared `conan:` imports are a hard error. See conan.md.

  // ─────────────────────────────────────────────────────────────
  // Generated .d.ts flavor
  // ─────────────────────────────────────────────────────────────
  dts: 'sync',
    // 'sync' (default) types the direct binding surface. 'promise' wraps every
    // generated method/function return in Promise<...> - use it when your app
    // runs with initNative({ useWorker: true }) (or any async bridge), where
    // every call resolves asynchronously at runtime. Constructors stay
    // sync-typed either way; write `await new X(...)` (a no-op on sync
    // runtimes, required under a worker). See lifecycle-and-types.md.

  types: false,
    // Package type publishing (opt-in): emit one combined .d.ts over every
    // public header into <output>/types/index.d.ts and wire package.json
    // (`types` + a greedy `typesVersions` "*.h" map), so consumers importing
    // '<pkg>/<any>.h' get full types. Combine with dts: 'promise' for
    // worker-first packages.

  // ─────────────────────────────────────────────────────────────
  // Paths (all relative to paths.project; see resolution rules below)
  // ─────────────────────────────────────────────────────────────
  paths: {
    config: import.meta.url,
      // ALWAYS SET THIS. Anchors all relative paths to this file's location.

    project: undefined,
      // Project root. Defaults to the dir of paths.config (or cwd if neither set).

    base: undefined,
      // Alternative project root override. Used by examples to point above
      // the workspace boundary in the monorepo.

    cache:  '.crossbind',                 // build cache root
    build:  '.crossbind/build',           // staging dir
    output: '.crossbind/build',           // dist artifacts (defaults to build)

    native: ['src/native'],
      // ARRAY. C++ source roots. Order matters for include precedence.

    module: undefined,                // SWIG .i interfaces; defaults to native
    header: undefined,                // headers; defaults to native
    bridge: undefined,                // bridge code; defaults to [...native, build]
    cmake:  undefined,                // override CMakeLists.txt path
  },

  // ─────────────────────────────────────────────────────────────
  // File extension filters
  // ─────────────────────────────────────────────────────────────
  ext: {
    header: ['h', 'hpp', 'hxx', 'hh'],
    source: ['c', 'cpp', 'cxx', 'cc'],
    module: ['i'],   // SWIG interfaces
  },

  // ─────────────────────────────────────────────────────────────
  // Export (output) settings
  // ─────────────────────────────────────────────────────────────
  export: {
    type: 'cmake',
      // 'cmake' — default; the C/C++ pipeline.
      // 'cargo' — the project is a Rust crate: crossbind runs `cargo build
      //           --release --target <triple>` per platform (wasm/android/ios;
      //           wasi has no wasip3 Rust target yet a