WebAssembly C++ Porting with Emscripten Tutorial [2026]

Moving heavy computation into the browser is no longer a stunt project. With Emscripten, you can compile portable C++ into WebAssembly, keep the performance-critical loops in native code, and call them from ordinary JavaScript. The trick is not just compiling successfully, but choosing an API boundary, build flags, and loading path that hold up in a real app. This walkthrough uses a small numeric kernel so you can reuse the pattern for larger libraries.

• -sMODULARIZE plus -sEXPORT_ES6 gives you an async ES module factory.
• -sEXPORTED_FUNCTIONS must include the functions you plan to call from JavaScript.
• The browser should fetch .wasm with the application/wasm MIME type.
• Keep the first port single-threaded; add -pthread only after the core path is stable.

Prerequisites

./emsdk update
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh
emcc -v

Step 1: Flatten the Library Boundary

The first porting decision is architectural, not compiler-related: decide what JavaScript should actually call. For most libraries, the safest path is to keep your internal C++ types private and expose a minimal C ABI for the browser-facing edge.

Why this approach works

• It avoids C++ name mangling issues at the JS boundary.
• It keeps your export list small, which helps code size.
• It lets you preserve the existing C++ internals while making data movement explicit.

Here is a tiny numeric kernel that computes a dot product over two buffers:

#include <cstddef>

extern "C" {
  double dot_product(const double* a, const double* b, int len) {
    double sum = 0.0;
    for (int i = 0; i < len; ++i) {
      sum += a[i] * b[i];
    }
    return sum;
  }
}

This example is intentionally simple, but the pattern scales well. Wrap only the library entry points you need, keep them stable, and pass plain numbers, pointers, and lengths. If your native library currently mixes computation with file I/O, threads, or platform APIs, split those concerns now.

• Move pure computation into a standalone translation unit.
• Replace OS-specific file reads with caller-provided buffers where possible.
• Delay threading until the single-threaded Wasm build is correct.

If you want prettier code snippets while documenting your migration internally, TechBytes’ Code Formatter is a useful cleanup step before sharing examples across teams.

Step 2: Compile with Emscripten

Now compile that C++ file into a browser-friendly module. The key settings here are -sMODULARIZE, which isolates the generated runtime and returns an async factory, and -sEXPORT_ES6, which emits an ES module. The official docs note that ES module output is enabled automatically when the output file ends in .mjs.

em++ src/dot_product.cpp \
  -O3 \
  -sMODULARIZE \
  -sEXPORT_ES6 \
  -sALLOW_MEMORY_GROWTH \
  -sEXPORTED_FUNCTIONS=_dot_product,_malloc,_free \
  -o web/dot_product.mjs

What each flag is doing

• -O3: optimize for runtime speed.
• -sMODULARIZE: generate an async factory instead of polluting the global scope.
• -sEXPORT_ES6: emit an ES module so you can use standard browser imports.
• -sALLOWMEMORYGROWTH: let the heap expand at runtime instead of aborting on the first memory ceiling.
• -sEXPORTED_FUNCTIONS: keep only the functions you need accessible from JS. Per the docs, native symbols in this list need a leading underscore.

That export list matters. Emscripten aggressively removes code it does not think you use. If you forget _dot_product, the build may still succeed, but the symbol will not be callable at runtime.

If your current integration plan depends on ccall or cwrap, export them explicitly with -sEXPORTEDRUNTIMEMETHODS=ccall,cwrap. For a first pass, direct function calls are leaner and easier to reason about.

Step 3: Load and Call Wasm from the Browser

With the module built, create a small ES module that loads the generated factory, allocates memory, copies typed-array data into Wasm memory, calls the exported function, and frees the buffers.

import createDotModule from './dot_product.mjs';

const wasm = await createDotModule();

const a = new Float64Array([1, 2, 3, 4]);
const b = new Float64Array([5, 6, 7, 8]);
const bytes = a.length * Float64Array.BYTES_PER_ELEMENT;

const ptrA = wasm._malloc(bytes);
const ptrB = wasm._malloc(bytes);

wasm.HEAPF64.set(a, ptrA / Float64Array.BYTES_PER_ELEMENT);
wasm.HEAPF64.set(b, ptrB / Float64Array.BYTES_PER_ELEMENT);

const result = wasm._dot_product(ptrA, ptrB, a.length);
console.log('dot_product =', result);

wasm._free(ptrA);
wasm._free(ptrB);

Then wire it into a minimal page:

<!doctype html>
<html lang='en'>
  <head>
    <meta charset='utf-8' />
    <title>Wasm Dot Product</title>
  </head>
  <body>
    <script type='module' src='./main.js'></script>
  </body>
</html>

Serve the page through a local server, not file://. The official Emscripten docs recommend emrun for this workflow:

emrun --no_browser --port 8080 web/index.html

Open http://localhost:8080/web/index.html in your browser and check the console. This server-based step is important because browsers commonly block local file:// loading for the extra assets a Wasm app needs.

Verification and Expected Output

Your first verification target is correctness, not benchmarking. The vectors in the sample are small enough to validate mentally:

• 1*5 + 2*6 + 3*7 + 4*8 = 70
• The browser console should print dot_product = 70.
• The network panel should show both the generated module and the .wasm payload loading successfully.

dot_product = 70

Sanity-check list

1. Refresh the page and confirm the result is stable across reloads.
2. Increase the input size and confirm the function still returns expected values.
3. Watch browser memory while repeating the call to verify that your _free calls are actually happening.

Only after that should you start measuring. Once the call path is correct, scale up the arrays, time native vs. Wasm runs, and decide whether the crossing cost between JS and Wasm is small enough for your workload. In many real ports, the biggest win comes from batching more work into one Wasm call instead of ping-ponging per element.

Troubleshooting and What's Next

Top 3 issues you will actually hit

• The browser fails to stream or instantiate the Wasm file. Make sure the server returns the file with application/wasm. MDN explicitly notes that WebAssembly.instantiateStreaming() depends on the correct MIME type.
• An exported function is missing at runtime. Add it to -sEXPORTED_FUNCTIONS with the leading underscore. If you rely on ccall or cwrap, also export them through -sEXPORTEDRUNTIMEMETHODS.
• Your threaded build works locally but fails after deploy. Emscripten’s pthreads support requires SharedArrayBuffer, and browsers gate that behind COOP and COEP headers. Do not enable -pthread unless your hosting setup can send those headers correctly.

What's next

• Replace the toy kernel with one real function from your library and keep the same JS harness.
• Move from hand-written compile commands to your existing build system once the flags are stable.
• Batch larger workloads into fewer Wasm calls to reduce boundary overhead.
• Consider Embind later if you need class-like JS ergonomics; keep the first port focused on a minimal ABI.
• Introduce -pthread only when profiling shows CPU parallelism is the next bottleneck and your deployment can satisfy the browser security model.

That progression keeps risk low: first prove the computational core compiles and runs, then improve ergonomics, then optimize deployment details. For most teams, that order is the difference between a demo and a maintainable browser-side native port.