Portable C++ can run in the browser through WebAssembly using Emscripten, modular JS glue, and exported APIs. Step-by-step guide with code. Read now.
Why Portable C++ Belongs in the Browser
WebAssembly lets you take existing C++ logic—parsers, codecs, simulation kernels, or numerical routines—and run it inside the browser at near-native speed without rewriting the core in JavaScript. The usual path is Emscripten: a toolchain that compiles C or C++ to Wasm, then ships a modular JS glue layer that loads the module, wires memory, and exposes the functions you choose to call from the page.
The goal is not to replace the whole front end. Keep UI, routing, and DOM work in JavaScript or TypeScript. Export a small, stable API from C++ for the work that is already proven in native code or that benefits from tight memory control. That split keeps the port focused and the browser side easy to maintain.
Set Up Emscripten and Define What You Export
Install the Emscripten SDK, activate its environment, and start from a minimal C++ entry point that does real work—not a full application shell. Prefer free functions or a thin C-compatible wrapper around C++ classes so the boundary stays simple. Mark only the symbols the page needs, and compile with flags that emit modular ES-style glue instead of a global script that pollutes window.
A practical compile shape looks like this: enable WebAssembly output, request modularization so you get a factory that returns a promise for the instance, and list exported functions by name. Keep heap growth and file-system options intentional; default settings often pull in more runtime than a library needs. Iterate on a single function first—hash a buffer, transform a matrix, decode a chunk—then expand exports once load and call paths are solid.
- Export a narrow surface: init, process, dispose—not the whole class hierarchy.
- Pass lengths with pointers; do not assume null-terminated strings across the boundary.
- Treat the Wasm heap as owned by the module; copy results out when JS must retain data.
Modular JS Glue and Calling the Module
Modular glue means your app imports a factory, awaits instantiation, then calls named C functions through the instance. Allocate input in Wasm memory (or use typed views into the heap), write bytes from JavaScript, invoke the export, and read results back. Always free temporary buffers you allocated on the C++ side so long sessions do not leak.
Handle the async load path explicitly: show a loading state, catch instantiate failures, and version your .wasm asset so caches do not serve a binary that no longer matches the glue. If the same module runs in a worker, keep the protocol message-based—send ArrayBuffers, receive results—so the main thread stays responsive while C++ runs.
Porting Pitfalls and a Safe Checklist
Most pain comes from assumptions that hold on the desktop but not in the browser: blocking I/O, unbounded stack use, reliance on a full POSIX environment, or hidden global state across “requests.” Prefer pure functions with explicit inputs and outputs. Where you need files, use virtual mounts or feed data from JS rather than assuming disk paths. Watch for undefined behavior that optimizers expose only under Wasm’s stricter runtime.
Ship the port in layers: compile and unit-test the C++ core natively when you can, then recompile with Emscripten and re-run the same cases against the module. Add one integration test that loads the modular glue in a real page or worker and asserts known inputs produce known outputs. Document the exported API, memory ownership rules, and build command next to the source so the next change does not guess at flags. With that discipline, portable C++ becomes a reliable browser component rather than a one-off experiment.