WASM Development
Building and integrating WebAssembly. First pick the toolchain, then handle the
three concerns that bite regardless of toolchain: the memory boundary, threading,
and CSP.
1. Choose the toolchain
| Source language |
Toolchain |
Build command |
Fits when |
| C / C++ |
Emscripten (emcc / em++) |
emcc src.c -o out.mjs |
Porting existing C/C++, SDL/OpenGL apps, large native libs, when you need the Emscripten runtime (filesystem, pthreads glue) |
| Rust |
wasm-pack + wasm-bindgen |
wasm-pack build --target web |
Greenfield WASM, tight JS interop with rich types, small self-contained modules, when you want generated TypeScript .d.ts |
Both emit a .wasm plus a JS loader/glue file. Do not hand-write the glue —
each toolchain generates it and keeps the ABI in sync.
- C/C++ deep dive: emscripten-patterns.md
- Rust deep dive: rust-wasm-patterns.md
2. The JS/WASM boundary is the hard part
WASM memory is a single linear ArrayBuffer. You cannot pass JS objects,
strings, or arrays directly — you pass numbers (i32/i64/f32/f64), which for
anything larger than a scalar means a pointer (an offset into that buffer).
- Small scalars cross for free as function args/returns.
- Strings / structs / typed arrays must be marshalled: allocate inside WASM
memory (
Module._malloc / a wasm-bindgen accessor), copy the bytes in, pass the
pointer, and free it afterwards. Emscripten's cwrap/Embind and Rust's
wasm-bindgen generate this copy for you.
- Large data (e.g. video frames) is either copied into WASM memory or
shared by taking a
TypedArray view directly over WebAssembly.Memory.buffer
and having WASM write into it — no copy, but you own the lifetime.
Marshalling patterns, the detached-buffer gotcha after memory growth, and worker
message passing: js-wasm-integration.md.
3. Run heavy WASM off the main thread
CPU-bound WASM on the main thread freezes the UI. Move it to a Web Worker:
- Instantiate with
WebAssembly.instantiateStreaming(fetch(url), imports) inside
the worker (streaming compile — the server MUST serve application/wasm).
- Ship data in and out with
postMessage; transfer ArrayBuffers as
Transferables (worker.postMessage(buf, [buf])) to avoid a structured-clone
copy.
Full worker + transferable pattern: js-wasm-integration.md.
4. CSP: WASM needs an explicit allowance
Under a strict Content-Security-Policy, instantiating WebAssembly requires
'wasm-unsafe-eval' in script-src — not 'unsafe-eval' (that older, broader
directive also works but grants JS eval, which you do not want):
Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval';
Get the policy reviewed — see the sibling ../security-review/SKILL.md.
Threading (SharedArrayBuffer) adds COOP+COEP header requirements — covered in
emscripten-patterns.md.
5. Size matters — a .wasm is downloaded and compiled on every load
Always run the binary through wasm-opt and strip it before shipping. Measure the
gzip/brotli bytes, do not guess — read the artifact, not a tool's summary line
(../../rules/evidence-discipline.md).
Optimization levels, SIMD, and how to measure:
optimization.md. Attribute the bytes and gate the
size with the sibling ../bundle-analysis/SKILL.md.
6. When it breaks
memory access out of bounds, unreachable executed, and function-signature
traps have specific causes. Source-level stepping needs DWARF (Chrome DevTools
C/C++ extension) or source maps: debugging.md.
References
- emscripten-patterns.md — emcc/em++ and CMake flags, Embind vs ccall/cwrap, filesystems, pthreads.
- rust-wasm-patterns.md — wasm-pack targets,
#[wasm_bindgen], JsValue, serde, closures, web-sys/js-sys.
- js-wasm-integration.md — loading, memory sharing, workers, error handling across the boundary.
- optimization.md — wasm-opt, dead code, SIMD, and measuring.
- debugging.md — DWARF/source maps, common RuntimeErrors, profiling.
1---2name: wasm-development3description: "Build and integrate WebAssembly across both major toolchains — C/C++ via Emscripten (emcc/em++) and Rust via wasm-pack + wasm-bindgen. Covers the JS/WASM memory boundary, off-main-thread execution in Web Workers, CSP requirements, size optimization, and debugging. Use when the user wants to build WASM, compile C/C++ or Rust to WebAssembly, set up Emscripten or wasm-pack, call a WASM module from JavaScript, pass data across the JS/WASM boundary, or shrink/debug a .wasm binary. Triggers on: build WASM, Emscripten, wasm-pack, WebAssembly, wasm-bindgen, WASM module."4metadata:5 source: https://skillmd.com/skills/decebal/wasm-development6---78# WASM Development910Building and integrating WebAssembly. First pick the toolchain, then handle the11three concerns that bite regardless of toolchain: the memory boundary, threading,12and CSP.1314## 1. Choose the toolchain1516| Source language | Toolchain | Build command | Fits when |17|---|---|---|---|18| C / C++ | Emscripten (`emcc` / `em++`) | `emcc src.c -o out.mjs` | Porting existing C/C++, SDL/OpenGL apps, large native libs, when you need the Emscripten runtime (filesystem, pthreads glue) |19| Rust | wasm-pack + wasm-bindgen | `wasm-pack build --target web` | Greenfield WASM, tight JS interop with rich types, small self-contained modules, when you want generated TypeScript `.d.ts` |2021Both emit a `.wasm` plus a JS loader/glue file. Do **not** hand-write the glue —22each toolchain generates it and keeps the ABI in sync.2324- C/C++ deep dive: [emscripten-patterns.md](references/emscripten-patterns.md)25- Rust deep dive: [rust-wasm-patterns.md](references/rust-wasm-patterns.md)2627## 2. The JS/WASM boundary is the hard part2829WASM memory is a single linear `ArrayBuffer`. You **cannot** pass JS objects,30strings, or arrays directly — you pass **numbers** (i32/i64/f32/f64), which for31anything larger than a scalar means a **pointer** (an offset into that buffer).3233- **Small scalars** cross for free as function args/returns.34- **Strings / structs / typed arrays** must be marshalled: allocate inside WASM35 memory (`Module._malloc` / a wasm-bindgen accessor), copy the bytes in, pass the36 pointer, and free it afterwards. Emscripten's `cwrap`/Embind and Rust's37 wasm-bindgen generate this copy for you.38- **Large data (e.g. video frames)** is either **copied** into WASM memory or39 **shared** by taking a `TypedArray` view directly over `WebAssembly.Memory.buffer`40 and having WASM write into it — no copy, but you own the lifetime.4142Marshalling patterns, the detached-buffer gotcha after memory growth, and worker43message passing: [js-wasm-integration.md](references/js-wasm-integration.md).4445## 3. Run heavy WASM off the main thread4647CPU-bound WASM on the main thread freezes the UI. Move it to a **Web Worker**:4849- Instantiate with `WebAssembly.instantiateStreaming(fetch(url), imports)` inside50 the worker (streaming compile — the server MUST serve `application/wasm`).51- Ship data in and out with `postMessage`; transfer `ArrayBuffer`s as52 **Transferables** (`worker.postMessage(buf, [buf])`) to avoid a structured-clone53 copy.5455Full worker + transferable pattern: [js-wasm-integration.md](references/js-wasm-integration.md).5657## 4. CSP: WASM needs an explicit allowance5859Under a strict Content-Security-Policy, instantiating WebAssembly requires60`'wasm-unsafe-eval'` in `script-src` — **not** `'unsafe-eval'` (that older, broader61directive also works but grants JS `eval`, which you do not want):6263```64Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval';65```6667Get the policy reviewed — see the sibling [../security-review/SKILL.md](../security-review/SKILL.md).68Threading (SharedArrayBuffer) adds COOP+COEP header requirements — covered in69[emscripten-patterns.md](references/emscripten-patterns.md).7071## 5. Size matters — a `.wasm` is downloaded and compiled on every load7273Always run the binary through `wasm-opt` and strip it before shipping. Measure the74gzip/brotli bytes, do not guess — read the artifact, not a tool's summary line75([../../rules/evidence-discipline.md](../../rules/evidence-discipline.md)).76Optimization levels, SIMD, and how to measure:77[optimization.md](references/optimization.md). Attribute the bytes and gate the78size with the sibling [../bundle-analysis/SKILL.md](../bundle-analysis/SKILL.md).7980## 6. When it breaks8182`memory access out of bounds`, `unreachable executed`, and function-signature83traps have specific causes. Source-level stepping needs DWARF (Chrome DevTools84C/C++ extension) or source maps: [debugging.md](references/debugging.md).8586## References8788- [emscripten-patterns.md](references/emscripten-patterns.md) — emcc/em++ and CMake flags, Embind vs ccall/cwrap, filesystems, pthreads.89- [rust-wasm-patterns.md](references/rust-wasm-patterns.md) — wasm-pack targets, `#[wasm_bindgen]`, JsValue, serde, closures, web-sys/js-sys.90- [js-wasm-integration.md](references/js-wasm-integration.md) — loading, memory sharing, workers, error handling across the boundary.91- [optimization.md](references/optimization.md) — wasm-opt, dead code, SIMD, and measuring.92- [debugging.md](references/debugging.md) — DWARF/source maps, common RuntimeErrors, profiling.