← All templates

Small binaries, no hidden allocations across the boundary, typed bindings.

Constitution — WebAssembly module

Version 1.0.0 · Ratified 2026-11-10

These principles hold for every spec, plan and task of the module. A spec may add rules; it never weakens these.

  1. Small binaries. The release .wasm has a size budget in the plan (for example 200 KB gzipped), checked in CI after wasm-opt -Oz. The release profile uses opt-level = "z", LTO and panic = "abort", and a dependency that breaks the budget needs approval.

  2. No hidden allocations across the boundary. Large data crosses between JavaScript and Wasm through views into linear memory or caller-provided buffers, not by copying strings and vectors on every call. Each exported function documents who owns the memory it returns.

  3. Typed bindings. The JavaScript API is generated by wasm-bindgen with TypeScript definitions, and callers never touch raw pointers. The generated .d.ts is checked in CI against a TypeScript usage test.

  4. Chunky calls, not chatty ones. The boundary is crossed once per unit of work, not once per item. An API that needs a call per element of a large array is redesigned before it ships.

  5. Tested in the hosts that use it. Logic is tested with cargo test natively, and the bindings run with wasm-bindgen-test in a headless browser and in Node in CI. Errors cross the boundary as typed JavaScript errors, never as a trap.