API · cpp.js · Config

Config

cpp.js's build-time configuration, read by the cppjs build CLI and never consumed at runtime (the runtime knobs are initCppJs options). Two files: cppjs.config.js, which every consumer writes, and cppjs.build.js, which only package authors write.

USING GDAL, NOT BUILDING IT Most apps never touch these files: you install gdal3.js + the bundler plugin and go. This page matters when you build a custom GDAL bundle (drop dependencies, change flags, target a platform) or author a @cpp.js/package-*.

cppjs.config.js

The project build config. gdal3.js's own apps are tiny, they just pull in the prebuilt GDAL config:

cppjs.config.js

import gdal from "@cpp.js/package-gdal/cppjs.config.js";

export default {
  general: { name: "my-geo-app" },
  dependencies: [gdal],
  paths: { config: import.meta.url },   // always set this
};

FIELD	MEANING
`general.name`	Logical app/lib name. Drives output binary names (`lib<name>.a`, `<name>.xcframework`) and the browser FS namespace `/opfs/<name>/`.
`dependencies`	Array of other cpp.js configs (e.g. `@cpp.js/package-gdal/cppjs.config.js`). Transitive deps flatten; if any is `runtime: "mt"`, the project auto-promotes to `mt`.
`target.runtime`	`"st"` or `"mt"`: single vs multi-threaded wasm. `mt` needs SharedArrayBuffer + COOP/COEP in the browser.
`paths.config`	Always set to `import.meta.url`; it anchors every other relative path.
`paths.*`	`project`, `base` (alt root, e.g. a monorepo), `cache` (`.cppjs`), `build`, `output`, `native` (array, order matters), `module`, `header`, `bridge`, `cmake`.
`ext`	Recognised extension lists: `header` (`h,hpp,hxx,hh`), `source` (`c,cpp,cxx,cc`), `module` (`i`).
`export`	How the lib is exported: `type: "cmake"`, `header`, `libPath`, `libName`, `binHeaders`.
`targetSpecs`	Per-target overrides: `{ filter, specs }`. Filter by `platform` / `arch` / `runtime` / `buildType` / `runtimeEnv`; `specs` set `cmake` (`-D` flags), `emccFlags`, `env`, `data` (preload into the `.data`), `ignoreLibName`.
`extensions`	Plugin objects with hooks at config-load / build boundaries. Use to share an override across packages.
`functions.isEnabled`	`(target) => boolean`: override the default "is this target buildable?" check.

cppjs.build.js

Package authors only. This file lives inside a @cpp.js/package-* and tells cpp.js how to fetch and compile an upstream C/C++ library; consumer apps never write it. The CLI merges its exports into the build. This is what gdal3.js's "override the build" really means, e.g. @cpp.js/package-gdal-wasm/cppjs.build.js patches GDAL sources and copies files in.

FIELD	MEANING
`getURL(version)` · `getSource(state)`	Source acquisition: a tarball URL, or a custom clone/copy/generate step.
`buildType`	`"cmake"` or `"configure"`.
`getBuildParams(state, target)`	cmake `-D` flags / configure args.
`env(target)`	Build-time `CFLAGS` / `CXXFLAGS` / `LDFLAGS` (distinct from the runtime `env`).
`getExtraLibs(target)`	Extra link libraries.
`replaceList` · `sourceReplaceList`	Regex-patch upstream source before building.
`copyToSource` · `copyToDist`	Copy files into the source tree / the output.
`setState` · `beforeRun` · `prepare` · `build`	Lifecycle hooks; `build` can replace the whole build step.

Overrides

When you need to change behaviour, cpp.js documents an order of preference, least to most invasive:

A target filter (build only what you need).
targetSpecs[].specs.* in cppjs.config.js.
env: {} in cppjs.config.js.
cppjs.build.js hooks (package authors).
extensions[] (shared plugins).
~/.cppjs.json (machine-wide): XCODE_DEVELOPMENT_TEAM, RUNNER (DOCKER_RUN / DOCKER_EXEC / LOCAL), LOG_LEVEL (INFO / DEBUG).

The full cpp.js configuration and override reference lives at cpp.js.org.

← PREVModule helpers NEXT →Headers as modules