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: One-line overview + live code demo
• Getting started — for developers: Install, scaffold a project, first build
• Agent guide — for AI coding agents: Three install layers + concrete dialog examples

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

Single source of truth at cppjs-agents/ — same skills, commands, and MCP tools across all clients.

• Claude Code plugin: 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: Same skills + commands via Cursor marketplace. Install: Cursor → Settings → Plugins → Add from GitHub bugra9/cpp.js.
• OpenAI Codex CLI plugin: Skills + interface metadata for Codex. Install: Add bugra9/cpp.js to ~/.agents/plugins/marketplace.json, then codex plugin install cppjs.
• GitHub Copilot CLI plugin: Skills + MCP server reference + .github/copilot-instructions.md. Auto-discovers when running in this repo.
• Gemini CLI extension: MCP server registration + GEMINI.md context. Install: gemini extension install https://github.com/bugra9/cpp.js.
• OpenCode integration: Add cppjs MCP to your opencode.json. Optionally symlink skills.
• @cpp.js/mcp — MCP server: Universal fallback — any MCP-aware client (Claude Desktop, Cline, custom clients). 9 typed tools. Install: npx -y @cpp.js/mcp.
• Skills CLI (50+ agents): 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: Vendor-neutral, zero install. Paste into your project's AGENTS.md / GEMINI.md / .github/copilot-instructions.md.

Runtime / Config API reference

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

Workflow playbooks

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

Optional

• Architecture decisions (ADR): Load-bearing technical decisions and why
• Raw AGENTS.md context: The agent-context file the AI itself reads when working inside the cpp.js repo
• GitHub repository: Source code
• Contributing guide: How to contribute (branch naming, commit format, test reqs, beta release)
• Full documentation as one file: Concatenated agent + API + ADR + playbooks markdown for direct context-window loading