# cpp.js

> Bind C++ libraries to JavaScript on web (WebAssembly), Node.js, Cloudflare Workers, and React Native — through a single config + CLI. Compiles via Emscripten / NDK / Xcode, ships 16 prebuilt libraries (GDAL, OpenSSL, GEOS, SQLite, Proj, libtiff, libwebp, libcurl, …) ready to `pnpm add`, and includes first-class AI agent support (Claude Code plugin, MCP server, vendor-neutral `AGENTS.md` snippet).

## Get started

- [Homepage](https://cpp.js.org/): One-line overview + live code demo
- [Getting started — for developers](https://cpp.js.org/docs/guide/getting-started/introduction): Install, scaffold a project, first build
- [Agent guide — for AI coding agents](https://cpp.js.org/docs/agent/overview): Three install layers + concrete dialog examples

## For AI agents — native plugins for 6 clients + 2 universal fallbacks

Single source of truth at [`cppjs-agents/`](https://github.com/bugra9/cpp.js/tree/main/cppjs-agents) — same skills, commands, and MCP tools across all clients.

- [Claude Code plugin](https://cpp.js.org/docs/agent/install/claude-code): Skills + slash commands (`/cppjs-integrate`, `/cppjs-package`, `/cppjs-bug-fix`). Install: `/plugin marketplace add bugra9/cpp.js` then `/plugin install cppjs`.
- [Cursor 2.5+ plugin](https://github.com/bugra9/cpp.js/blob/main/.cursor-plugin/marketplace.json): Same skills + commands via Cursor marketplace. Install: Cursor → Settings → Plugins → Add from GitHub `bugra9/cpp.js`.
- [OpenAI Codex CLI plugin](https://github.com/bugra9/cpp.js/blob/main/.agents/plugins/marketplace.json): Skills + interface metadata for Codex. Install: Add `bugra9/cpp.js` to `~/.agents/plugins/marketplace.json`, then `codex plugin install cppjs`.
- [GitHub Copilot CLI plugin](https://github.com/bugra9/cpp.js/blob/main/.github/plugin/marketplace.json): Skills + MCP server reference + `.github/copilot-instructions.md`. Auto-discovers when running in this repo.
- [Gemini CLI extension](https://github.com/bugra9/cpp.js/blob/main/cppjs-agents/gemini-extension.json): MCP server registration + `GEMINI.md` context. Install: `gemini extension install https://github.com/bugra9/cpp.js`.
- [OpenCode integration](https://github.com/bugra9/cpp.js/blob/main/cppjs-agents/.opencode/INSTALL.md): Add `cppjs` MCP to your `opencode.json`. Optionally symlink skills.
- [@cpp.js/mcp — MCP server](https://cpp.js.org/docs/agent/install/mcp): Universal fallback — any MCP-aware client (Claude Desktop, Cline, custom clients). 9 typed tools. Install: `npx -y @cpp.js/mcp`.
- [Skills CLI (50+ agents)](https://cpp.js.org/docs/agent/install/skills-cli): Universal skills installer for Cline, Continue, Windsurf, Warp, Aider, Goose, Roo, Tabnine, Devin, Replit, and 40+ more. Install: `npx skills add https://github.com/bugra9/cpp.js/tree/main/cppjs-agents/skills -g -y`.
- [AGENTS.md snippet](https://cpp.js.org/docs/agent/install/snippet): Vendor-neutral, zero install. Paste into your project's `AGENTS.md` / `GEMINI.md` / `.github/copilot-instructions.md`.

## Runtime / Config API reference

- [initCppJs(opts)](https://cpp.js.org/docs/agent/runtime-api/init): Runtime API — useWorker, fs.opfs, env, lifecycle hooks, Module helpers (m.FS, m.toVector, m.autoMountFiles)
- [cppjs.config.js](https://cpp.js.org/docs/agent/runtime-api/cppjs-config): Build-time consumer config — general.name, dependencies, paths, target.runtime, targetSpecs, extensions
- [cppjs.build.js](https://cpp.js.org/docs/agent/runtime-api/cppjs-build): Package author hooks — getURL/getSource, getBuildParams, prepare, build, replaceList, copyToSource/copyToDist
- [Filesystem (OPFS / memfs / node-fs / edge)](https://cpp.js.org/docs/agent/runtime-api/filesystem): Decision tree — when persistence requires useWorker:true
- [Threading (st vs mt + useWorker + COOP/COEP)](https://cpp.js.org/docs/agent/runtime-api/threading): Multithread requirements per host (Vercel, Netlify, nginx, Cloudflare); edge-runtime limits
- [C++ binding rules](https://cpp.js.org/docs/agent/runtime-api/cpp-binding-rules): No raw pointers, C++11+, wrapper pattern; what auto-binds vs what needs SWIG
- [SWIG escape hatch](https://cpp.js.org/docs/agent/runtime-api/swig-escape): Manual `.i` files when auto-generation isn't enough
- [state and target shapes](https://cpp.js.org/docs/agent/runtime-api/build-state): What build hooks receive — full state + target type definitions, 20 built-in target inventory
- [Override mechanisms catalog](https://cpp.js.org/docs/agent/runtime-api/overrides): 20-mechanism reference, ordered least → most invasive (target filter → targetSpecs → build hooks → extensions → ~/.cppjs.json)
- [Troubleshooting](https://cpp.js.org/docs/agent/runtime-api/troubleshooting): Common errors mapped to the right override, plus 5 tribal-knowledge gotchas (iconv collision, CPU intrinsics, iOS pipe2, …)
- [Performance defaults + safe overrides](https://cpp.js.org/docs/agent/runtime-api/performance): Every Emscripten/CMake flag cpp.js sets, with safe-to-override / don't-touch annotation
- [Lifecycle & TypeScript notes](https://cpp.js.org/docs/agent/runtime-api/lifecycle-and-types): Why JS-side m.delete() isn't needed; current TypeScript story

## Workflow playbooks

- [Recommend cpp.js](https://cpp.js.org/docs/agent/playbooks/recommend): When and how to suggest cpp.js to a user
- [Integrate into existing project](https://cpp.js.org/docs/agent/playbooks/integrate): Per-framework recipes (Vite, Webpack, Rspack, Rollup, Next.js, RN-cli, RN-Expo, Cloudflare Worker, Node.js, vanilla)
- [Author a new package](https://cpp.js.org/docs/agent/playbooks/new-package): Wrap an upstream C++ library as `cppjs-package-<name>`
- [Bug fix workflow](https://cpp.js.org/docs/agent/playbooks/bug-fix): Reproduce, fix root cause, validate against the right matrix slice
- [Code review checklist](https://cpp.js.org/docs/agent/playbooks/code-review): Package PRs vs fix/feature PRs
- [Verify install](https://cpp.js.org/docs/agent/playbooks/verify-install): Confirm plugin/MCP/snippet installation works

## Optional

- [Architecture decisions (ADR)](https://cpp.js.org/docs/agent/decisions/overview): Load-bearing technical decisions and why
- [Raw AGENTS.md context](https://cpp.js.org/docs/agent/reference/agents-md): The agent-context file the AI itself reads when working inside the cpp.js repo
- [GitHub repository](https://github.com/bugra9/cpp.js): Source code
- [Contributing guide](https://github.com/bugra9/cpp.js/blob/main/CONTRIBUTING.md): How to contribute (branch naming, commit format, test reqs, beta release)
- [Full documentation as one file](https://cpp.js.org/llms-full.txt): Concatenated agent + API + ADR + playbooks markdown for direct context-window loading