Config reference

libcascade.config.ts is the single source of truth for a custom build. The CLI looks for libcascade.config.ts, libcascade.config.js, or libcascade.config.mjs in the working directory, or the path you pass to --config. It is loaded with jiti, so a TypeScript config needs no build step.

import { defineBuild } from '@libcascade/toolchain';

export default defineBuild({
  name: 'myapp',
  bindings: ['gp_Pnt', 'TopoDS_Shape'],
  variants: [{ name: 'single' }],
});

defineBuild is an identity function — it returns its argument unchanged. Its entire job is to attach types.

Fields

bindings

The element type is the generated OcctSymbol union — 6,257 string literals covering every OCCT class and enum in the release, every OCCT typedef alias the bindgen resolves (TColgp_Array1OfPnt → NCollection_Array1_gp_Pnt), and the Embind builtins — plus exactly the symbols this config's own customBindings declare.

bindings: ['BRepPrimAPI_MakeBoox'],
//          ^ Type '"BRepPrimAPI_MakeBoox"' is not assignable…
//            Did you mean '"BRepPrimAPI_MakeBox"'?

Base classes and NCollection_* members of a bound class are auto-discovered at codegen time, so the list holds classes you instantiate or pass around, not their transitive closure.

The custom-symbol union is inferred only from customBindings[].symbols. That is deliberate: a typo'd OCCT name cannot silently widen the union and type itself as valid.

customBindings

customBindings: [
  { file: 'wrappers/mesh-extractor.cpp', symbols: ['MyMeshData', 'MyMeshExtractor'] },
  { file: 'build-configs/free-functions.cpp', symbols: ['TopoDS_Cast'], scope: 'main' },
],

See Extend with C++ for which scope to pick.

settings

EmccSettings is generated from the image's own emsdk settings.js (6.0.5) plus emcc's legacy/deprecated tables — 312 settings, each carrying its upstream documentation as JSDoc, so hovering a setting in your editor shows what emcc says about it. Legacy names such as USE_PTHREADS are typed and marked @deprecated.

Values whose grammar emcc constrains are typed structurally rather than as string:

Serialization at render time:

There is no index signature on EmccSettings. That is what makes an unknown -s name a compile error — and why anything the typed surface cannot express belongs in rawFlags.

compilerFlags

Only the non--s flags the reference builds actually use are modelled.

Anything else — -mrelaxed-simd, -Wl,--allow-undefined, --emit-symbol-map, -pthread — goes in rawFlags.

The rendered flag order is fixed: exceptions → -s settings → -flto → --no-entry → -msimd128 → optimisation → base rawFlags → variant rawFlags. emcc treats distinct flags as order-insensitive.

variants

variants: [
  { name: 'single', settings: { EVAL_CTORS: 2 } },
  {
    name: 'multi',
    compilerFlags: { threads: true },
    settings: { SHARED_MEMORY: true, PTHREAD_POOL_SIZE: 'navigator.hardwareConcurrency' },
  },
],

A variant's capabilities select its container image at build time and become the probes the generated createInstance runs before returning an instance.

Base keys keep their declaration order when a variant overrides them in place; variant-only keys are appended. null is how the multi-threaded variant drops the base EVAL_CTORS — constructor evaluation order is non-deterministic under pthread workers. Unsetting a key the base never declared is a configuration error, caught at load.

A single-variant config is first class: variants: [{ name: 'single' }] emits no selector machinery at assemble time.

Variants share one bindings list on purpose. That is what lets assemble emit one types.d.ts for all of them — see Variants and assemble.

Load-time validation

Types cannot see the filesystem. libcascade build, assemble, and check all validate the loaded config first and report every problem at once, with resolved absolute paths:

• empty name, empty bindings, empty variants
• duplicate variant names
• a variant null-unsetting a setting the base never declared
• a customBindings.file that does not exist on disk
• a customBindings entry declaring no symbols

Worked references

Two real configs ship in the open:

• libcascade.config.ts — the full build itself: every OCCT symbol, one scope: 'main' wrapper file, single + multi variants, assemble: { exports: 'eager' }.
• replicad-opencascadejs — a trimmed custom build: 11 wrapper files declaring 17 custom symbols, single + multi, assemble: { exports: 'factory' }.

Related

• CLI reference — the commands that consume this file.
• Driver environment — engine discovery, image override, digest pinning.
• Quickstart — from install to dist/.