AI Rules for WebAssembly Projects

Why WebAssembly Needs Specific AI Rules

WebAssembly operates in a unique space — it runs at near-native speed in browsers and server environments, but it has constraints that don't exist in either native or traditional web development. Memory is manually managed (no garbage collector in many Wasm languages), the boundary between JavaScript and Wasm has real performance costs, and binary size directly affects load time. AI assistants don't account for any of these constraints by default.

The most common AI failures in Wasm projects: allocating memory without freeing it (linear memory grows until the tab crashes), crossing the JS-Wasm boundary inside tight loops (serialization overhead dominates), generating massive Wasm binaries by including unused standard library functions, and ignoring the component model for modular Wasm.

These rules target the two most common Wasm toolchains: Rust (wasm-bindgen, wasm-pack) and C/C++ (Emscripten). The principles apply to any source language that compiles to Wasm.

Rule 1: Memory Management in Linear Memory

The rule: 'Every allocation in Wasm linear memory must have a corresponding deallocation. For Rust: use RAII (drop semantics) — ownership ensures cleanup. For C/C++: pair every malloc with free, use RAII wrappers where possible. Never expose raw pointers to JavaScript without a clear ownership contract — document who is responsible for freeing the memory.'

For Rust wasm-bindgen: 'Use wasm-bindgen's automatic memory management for types that cross the JS boundary. For complex data, serialize to JSON or use SharedArrayBuffer — don't pass raw pointers to JS. Use Box::into_raw only when JavaScript must own the memory, and provide an explicit free function.'

For Emscripten: 'Use embind or val for JS interop — they handle memory management for common types. For manual memory management, use _malloc and _free from the Module object. Never allocate in Wasm and forget to free from JS — this is the most common Wasm memory leak pattern.'

Every allocation has a deallocation — no orphaned memory in linear memory
Rust: RAII handles cleanup — Box::into_raw only with explicit free function
Emscripten: embind for safe interop — _malloc/_free for manual management
Document ownership: who allocates, who frees, when
Monitor memory.buffer.byteLength in development — detect growth trends

⚠️ Memory Leaks Crash Tabs

Wasm linear memory grows but never shrinks. Every allocation without a free grows memory until the browser tab crashes. Document ownership: who allocates, who frees, when.

Rule 2: Minimize JS-Wasm Boundary Crossings

The rule: 'Every call across the JS-Wasm boundary has serialization overhead. Batch operations: instead of calling a Wasm function 1000 times in a loop, pass an array and process it in one call. Use SharedArrayBuffer or typed arrays for bulk data transfer — don't serialize/deserialize JSON across the boundary. Keep the hot path entirely in Wasm or entirely in JS — never alternate.'

For data transfer: 'Use TypedArrays (Float32Array, Uint8Array) to share data between JS and Wasm without copying. Write data into Wasm's linear memory from JS using the exported memory buffer. For complex objects, serialize once on the JS side, pass the buffer, and deserialize in Wasm.'

AI assistants generate code that calls Wasm from JS in tight loops — the boundary crossing overhead can make Wasm slower than pure JS for small operations. One rule forces batching, which is often the difference between Wasm being 10x faster and 10x slower.

💡 Batch, Don't Loop

Calling Wasm from JS in a tight loop can make Wasm slower than pure JS due to boundary overhead. Pass an array and process in one call — batching is often the 10x speed difference.

Rule 3: Binary Size Optimization

The rule: 'Minimize Wasm binary size — every kilobyte adds to load time. For Rust: use wasm-opt (from binaryen) as a post-processing step. Set opt-level = "z" and lto = true in Cargo.toml [profile.release]. Use #[wasm_bindgen] only on functions that need JS exposure — not on internal helpers. Avoid panic infrastructure: set panic = "abort" in profile.release.'

For tree-shaking: 'Only export functions that JavaScript needs to call. Internal helper functions should not be exported. Use wasm-snip to remove unreachable functions. For Rust, avoid pulling in large std library features — use core and alloc where possible.'

For Emscripten: 'Use -Os or -Oz for size optimization. Use EXPORTED_FUNCTIONS to list only needed exports. Enable WASM_BIGINT if targeting modern browsers. Use -s FILESYSTEM=0 if file system emulation isn't needed — it adds significant binary size.'

Rust: opt-level 'z', lto = true, panic = 'abort', wasm-opt post-processing
Export only JS-facing functions — internals stay unexported
wasm-snip to remove unreachable code — wasm-opt for binary optimization
Emscripten: -Os, EXPORTED_FUNCTIONS whitelist, FILESYSTEM=0 if unused
Target: <100KB for UI components, <500KB for compute modules

ℹ️ Size Targets

Under 100KB for UI components, under 500KB for compute modules. Use wasm-opt, opt-level 'z', panic='abort', and export only JS-facing functions. Every KB adds to load time.

Rule 4: Wasm Component Model and WASI

The rule: 'For server-side Wasm, target WASI (WebAssembly System Interface) instead of browser-specific APIs. Use the component model for modular, composable Wasm modules. Define interfaces with WIT (Wasm Interface Type) for cross-language interop. Each component has a clear interface contract — inputs, outputs, and imported capabilities.'

For WASI: 'Use wasi-sdk or Rust's wasm32-wasip2 target for WASI compilation. Access filesystem, networking, and clock through WASI capabilities — never assume direct OS access. WASI provides sandboxed access — request only the capabilities your component needs.'

The component model is the future of Wasm modularity — it lets components written in different languages compose without manual FFI. AI assistants that don't know about it generate monolithic Wasm binaries. Your rules should specify whether your project uses components or classic Wasm modules.

Rule 5: Testing WebAssembly Code

The rule: 'Test Wasm code at three levels: unit tests in the source language (Rust tests, C++ tests), integration tests that exercise the JS-Wasm boundary (using wasm-bindgen-test or Emscripten test harness), and browser tests that verify the complete pipeline (Playwright or Cypress loading the Wasm module).'

For Rust: 'Use #[cfg(test)] for unit tests that run natively (fast, no browser needed). Use wasm-bindgen-test for tests that run in a real browser or Node.js — these test the actual Wasm compilation and JS interop. Use wasm-pack test for running both.'

For performance: 'Benchmark Wasm vs JS for your specific workload before committing to Wasm. Use performance.now() on both sides. Wasm wins for: compute-heavy loops, image/video processing, cryptography, simulation. JS wins for: DOM manipulation, small data transforms, string processing. Don't use Wasm for everything — use it where it genuinely outperforms JS.'

Complete WebAssembly Rules Template

Consolidated rules for WebAssembly projects.

Every allocation has a deallocation — document ownership across JS-Wasm boundary
Batch boundary crossings — TypedArrays for bulk data, never JS→Wasm in tight loops
Binary size: opt-level z, lto, panic=abort, wasm-opt, export only needed functions
WASI for server-side — component model for modular Wasm — WIT for interfaces
Three test levels: source-language unit, JS-Wasm integration, browser end-to-end
Benchmark before committing — Wasm wins on compute, JS wins on DOM and strings
SharedArrayBuffer for zero-copy data sharing when available
wasm-pack for Rust → Wasm toolchain — Emscripten for C/C++ → Wasm