Web assembly for frontend developers

a: ImageData): Promise<Uint8ClampedArray> { const wasm = await initWasm();

// Pass raw bytes directly to avoid structured clone overhead const result = wasm.apply_grayscale(imageData);

if (typeof result === 'string') { throw new Error(result); }

return new Uint8ClampedArray(result); }

### Step 4: Architecture Decisions & Rationale

1. **Lazy Instantiation:** WASM modules require streaming compilation and memory allocation. Importing at module evaluation time blocks the main thread. Dynamic `import()` defers loading until the feature is triggered, preserving initial paint metrics.
2. **Memory Transfer over Serialization:** Passing `ImageData` as a raw `Vec<u8>` avoids the structured clone algorithm overhead. JavaScript `Uint8ClampedArray` and WASM linear memory share the same underlying buffer when using `wasm-bindgen`'s `JsCast` and `js_sys::Uint8Array`.
3. **Worker Isolation:** For sustained compute workloads, instantiate the WASM module inside a Web Worker. This prevents main-thread blocking during initialization and execution. The worker boundary enforces clean separation between UI state and computational state.
4. **Type Safety Boundary:** `wasm-bindgen` generates TypeScript definitions automatically. Never bypass generated types with `any` in production. Explicit error handling (`Result<T, JsValue>`) prevents silent failures and enables graceful fallbacks.
5. **Optimization Pipeline:** Production builds must run `wasm-opt` via Binaryen. Debug builds include panic hooks and symbol tables that increase bundle size by 300-500%. Release builds with `-C opt-level=s` and `--strip-debug` are mandatory for frontend deployment.

## Pitfall Guide

### 1. Attempting DOM Manipulation from WASM
WASM runs in a sandboxed environment without access to the browser's rendering engine. Direct DOM calls will fail at compile time or runtime. 
**Best Practice:** Keep WASM strictly computational. Pass processed data back to JavaScript, which owns the DOM lifecycle. Use `web-sys` only for reading input buffers, not for rendering.

### 2. Ignoring Async Initialization Overhead
Synchronous `WebAssembly.instantiate()` blocks the main thread and triggers Lighthouse performance penalties. 
**Best Practice:** Always use async instantiation. Implement a loading state, pre-warm modules during idle time (`requestIdleCallback`), or use service workers to cache compiled modules.

### 3. Memory Leaks via Improper Ownership Transfer
Rust's ownership model doesn't automatically translate to JavaScript's garbage collector. Returning `Vec<u8>` creates a copy; failing to drop references in JS causes linear memory fragmentation.
**Best Practice:** Use `wasm-bindgen`'s `#[wasm_bindgen]` for complex types. When passing large buffers, use `js_sys::Uint8Array::view()` to share memory without copying. Explicitly call `drop()` in Rust or set JS references to `null` after use.

### 4. Shipping Unoptimized Builds
Debug WASM binaries include panic strings, debug symbols, and unoptimized control flow. Bundle size inflation directly impacts Time to Interactive.
**Best Practice:** Run `wasm-pack build --release --target web`. Post-process with `wasm-opt -Os -o output.wasm input.wasm`. Verify size with `wasm-size` and strip debug info in `Cargo.toml`.

### 5. Using WASM for Simple Logic
V8's TurboFan compiler optimizes simple loops, property access, and dynamic typing more efficiently than WASM's static execution model. Offloading `Array.map()` or string formatting to WASM introduces serialization overhead that negates performance gains.
**Best Practice:** Profile with Chrome DevTools Performance panel. Only migrate functions where CPU profiling shows sustained >16ms execution per frame or >50% of main thread time.

### 6. Poor Error Boundary Design
WASM panics unwind through the JS boundary and can crash the entire application if unhandled. 
**Best Practice:** Wrap WASM calls in `try/catch`. Use `std::panic::set_hook` in Rust to convert panics to `JsValue` errors. Implement fallback logic in TypeScript that degrades gracefully when WASM fails to load.

### 7. Benchmarking Without Cache Context
Cold-start benchmarks penalize WASM initialization, while warm benchmarks favor JS due to V8's inline caching. Neither reflects production reality.
**Best Practice:** Measure three phases: initialization, first execution, and sustained execution. Report p95 latency across 100 runs. Use `performance.now()` with high-resolution timestamps. Account for network caching and service worker precompilation in final metrics.

## Production Bundle

### Action Checklist
- [ ] Profile main thread CPU usage to identify compute-bound functions before introducing WASM
- [ ] Implement lazy dynamic import for WASM modules to defer initialization cost
- [ ] Configure `wasm-pack` with `--release --target web` and run `wasm-opt` post-build
- [ ] Establish explicit memory transfer patterns using `Uint8Array` views instead of structured cloning
- [ ] Wrap all WASM calls in async try/catch boundaries with TypeScript type guards
- [ ] Deploy WASM modules inside Web Workers for sustained compute workloads
- [ ] Add fallback logic to JavaScript when WASM initialization fails or is unsupported
- [ ] Benchmark cold vs warm execution and report p95 latency across 100 iterations

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Real-time image/video filtering | WASM in Worker | Compute-heavy, linear memory access, avoids main thread blocking | +150KB bundle, -40% CPU usage |
| Form validation & data formatting | JavaScript | V8 optimizes string/number operations; WASM serialization overhead negates gains | Baseline |
| Cryptographic hashing & encryption | WASM or Web Crypto API | Deterministic execution, constant-time operations, reduced side-channel risk | +80KB bundle, -60% CPU usage |
| DOM updates & event handling | JavaScript | WASM lacks DOM access; JS owns rendering pipeline natively | Baseline |
| Physics simulation & pathfinding | WASM in Worker | Tight loops, fixed-width math, predictable memory layout | +200KB bundle, -55% CPU usage |

### Configuration Template

**Cargo.toml**
```toml
[package]
name = "image_wasm"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
wasm-bindgen = "0.2"
js-sys = "0.3"
web-sys = { version = "0.3", features = ["ImageData"] }

[profile.release]
opt-level = "s"
lto = true
strip = "debuginfo"

vite.config.ts

import { defineConfig } from 'vite';
import wasm from 'vite-plugin-wasm';
import topLevelAwait from 'vite-plugin-top-level-await';

export default defineConfig({
  plugins: [wasm(), topLevelAwait()],
  build: {
    target: 'esnext',
    rollupOptions: {
      output: {
        format: 'es',
        inlineDynamicImports: false
      }
    }
  },
  optimizeDeps: {
    exclude: ['image_wasm']
  }
});

package.json scripts

{
  "scripts": {
    "build:wasm": "wasm-pack build ./src/wasm --release --target web --out-dir ../pkg",
    "optimize:wasm": "wasm-opt -Os -o src/pkg/image_wasm_bg.wasm src/pkg/image_wasm_bg.wasm",
    "build": "npm run build:wasm && npm run optimize:wasm && vite build",
    "dev": "vite"
  }
}

Quick Start Guide

1. Initialize Rust WASM Project: Run cargo new --lib wasm && cd wasm && cargo add wasm-bindgen js-sys web-sys. Create src/lib.rs with your compute function and annotate with #[wasm_bindgen].
2. Build & Export: Execute wasm-pack build --release --target web --out-dir ../pkg. This generates pkg/image_wasm.js, image_wasm_bg.wasm, and TypeScript definitions.
3. Configure Frontend Bundler: Install vite-plugin-wasm and vite-plugin-top-level-await. Add them to vite.config.ts. Set optimizeDeps.exclude to prevent Vite from pre-bundling WASM glue code.
4. Integrate & Test: Import the generated JS file dynamically in TypeScript. Call await wasm.default() before invoking exported functions. Pass Uint8Array buffers directly. Verify execution in Chrome DevTools Performance panel and confirm main thread remains unblocked.