Skip to main content

cpp.js

Bind C++ and Rust libraries to JavaScript on web (WebAssembly), Node.js, Cloudflare Workers, and React Native — through a single config + CLI — and build WASI command components that run under wasmtime. Compiles via Emscripten / wasi-sdk / cargo / NDK / Xcode, ships 16 prebuilt libraries (GDAL, OpenSSL, GEOS, SQLite, Proj, libtiff, libwebp, libcurl, …) ready to pnpm add — plus their upstream CLI tools as installable -bin-wasi npm packages (gdalinfo-wasi, ogr2ogr-wasi, …) — and includes first-class AI agent support (Claude Code plugin, MCP server, vendor-neutral AGENTS.md snippet).

Get started​

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
  • Rust bindings: cargo: crate imports, app-local .rs sources, export.type: 'cargo' packages; Rust→JS idiom table
  • WASI builds + CLI tools: platform: 'wasi' single-module command builds, -wasi prebuilts, -bin-wasi npm tool packages
  • 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, 30 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​

Optional​