cppjs-runtime-api

cppjs-runtime-api

Answer cpp.js runtime / config questions from the canonical reference docs, never from training-data guesses. The reference covers four surfaces; pick the one matching the question.

Routing table

User asks about	Load this doc	MCP topic
initCppJs(opts) parameters, return shape, Module helpers	docs/api/init.md	init
cppjs.config.js fields (consumer, build-time)	docs/api/cppjs-config.md	config
cppjs.build.js hooks (package author, build-time)	docs/api/cppjs-build.md	build
OPFS, memfs, persistence, file mounting, m.FS	docs/api/filesystem.md	filesystem
runtime: 'st' | 'mt', useWorker, COOP/COEP, edge limits	docs/api/threading.md	threading
C++ binding rules (no pointers, C++11+, wrapper pattern)	docs/api/cpp-binding-rules.md	binding-rules
Manual SWIG .i escape hatch	docs/api/swig-escape.md	swig
state / target shapes for build hooks; 20 built-in target inventory	docs/api/build-state.md	state
Catalog of override mechanisms (filter → targetSpecs → build hooks → extensions)	docs/api/overrides.md	overrides
Common errors mapped to fixes; tribal-knowledge gotchas	docs/api/troubleshooting.md	troubleshooting
Default Emscripten / CMake flags + safe-override guide	docs/api/performance.md	performance
Memory / object lifecycle in JS (none needed) + TypeScript notes	docs/api/lifecycle-and-types.md	lifecycle
Where to start	docs/api/README.md (decision tree)	index

GitHub mirrors of all docs:

• https://github.com/bugra9/cpp.js/blob/main/docs/api/<file>.md

How to use

1. Identify the surface the question lives in (runtime vs build-time, consumer vs package author, fs vs threading vs binding rules).
2. Pull the matching doc into context. Three ways:
   • MCP: call cppjs_get_api_reference({ topic: 'init' }) (or any topic from the table above).
   • Inside the monorepo: Read the file directly.
   • Outside the monorepo: WebFetch the GitHub URL.
3. Answer from the doc, with concrete examples. Don't paraphrase if the doc has the exact snippet.
4. Surface the load-bearing constraint. Most questions have a hidden constraint that bites users later — name it explicitly:
   • OPFS persistence → requires useWorker: true
   • runtime: 'mt' in production → requires COOP/COEP headers
   • Edge runtimes → no useWorker, no mt, no OPFS
   • paths.native is an array, not a string
   • C++ side: no raw pointers, C++11+ minimum, write a wrapper if upstream lib uses unbindable types
   • Defaults: -O3, -msimd128, -sALLOW_MEMORY_GROWTH=1, etc. — don't override speculatively
5. cppjs.config.js is build-time only. Putting useWorker: true in it does nothing — that's a runtime option for initCppJs(opts). Catch this confusion early.
6. Reach for the least invasive override. When a default doesn't fit, the order is: target filter → targetSpecs[].specs.* → cppjs.config.js env / functions → cppjs.build.js hooks → extensions[] → ~/.cppjs.json. See overrides.md.

The 5 most-asked questions (and the 1-line answer for each)

Use these to short-circuit obvious cases. Always offer to load the full doc for nuance.

1. "How do I get persistent storage in browser?" → useWorker: true, then write to /opfs/<appName>/. See filesystem.md.

2. "How do I make cpp.js multithreaded?" → target.runtime: 'mt' in cppjs.config.js + COOP/COEP headers in production. See threading.md.

3. "What does useWorker actually do?" → Spawns the Wasm module in a Web Worker; everything becomes async via Comlink. Required for OPFS, optional for parallelism (separate from runtime: 'mt'). See init.md + threading.md.

4. "Can I use cpp.js on Cloudflare Workers?" → Yes, but only runtime: 'st' + memory fs. No useWorker, no OPFS, no mt — edge runtimes don't expose the Worker API. See threading.md "Edge runtime limits".

5. "What fields go in cppjs.config.js?" → general.name, dependencies[], paths.{config, project, native[], output, …}, target.runtime, export.{type, libName[]}. See cppjs-config.md for the full shape with defaults.

Don't

• Don't answer cpp.js API questions from training-data assumptions. The API has evolved; load the current doc.
• Don't conflate cppjs.config.js (build-time) with initCppJs(opts) (runtime). Different surfaces, different fields.
• Don't conflate useWorker: true with runtime: 'mt'. They're orthogonal axes (see the matrix in threading.md).
• Don't suggest writing cppjs.build.js to a consumer — that file is package-author-only.
• Don't omit the COOP/COEP heads-up when the user is shipping a mt build to production. It's the #1 reason mt "works in dev, fails in prod".

Reference

Full index: https://github.com/bugra9/cpp.js/blob/main/docs/api/README.md