WebAssembly Best Practices

Rules for WASM modules with clear interop boundaries and minimal payload size.

How to Use This List

Apply before shipping WASM to production browsers or edge runtimes
Treat every JS boundary crossing as a performance and ABI contract
Measure wasm file size gzipped, not just raw bytes

A - Boundary Design

Batch work per exported function. Amortize JS/WASM call overhead.
Return owned data. Prefer Vec<u8> / String over long-lived borrows.
Map errors to host types. Result<JsValue, JsValue> in browsers; integer codes in WASI.
Avoid panics in exports. Use console_error_panic_hook in dev only.

B - Size and Build

Release profile tuned for size. opt-level = "s", LTO, panic = "abort".
Run wasm-opt in CI. Track size regressions on every merge.
Minimal web-sys features. Enable only APIs you import.
Audit dependency tree. default-features = false where possible.

C - Runtime Behavior

Await init() before calls. Document startup in README and TS types.
Respect single-thread default. Use threads only when SharedArrayBuffer is available.
Preallocate buffers. Reduce WASM memory growth in hot loops.
Serve correct MIME type. application/wasm with compression.

D - Security and Ops

Validate all host input. Treat JS strings and byte slices as untrusted.
CSP compatible loading. Avoid eval; use module imports.
Pin toolchain versions. wasm-bindgen, wasm-pack, and Rust channel in CI.
Source maps for dev only. Do not ship full debug symbols to prod CDN.

E - Architecture Choices

Rust for compute, JS for DOM glue. Unless team commits to Leptos/Yew fully.
Choose target deliberately. wasm32-unknown-unknown vs wasm32-wasi vs components.
Fallback path. Graceful degradation when WASM fails to load.
SSR when SEO matters. Client-only WASM pages index poorly.

FAQs

When is WASM worth it?

CPU-heavy, portable logic: parsers, crypto, simulations, image/audio codecs.

Maximum module size?

Keep auxiliary modules under ~100 KB gzipped; split larger apps into lazy chunks.

How many exports?

Few coarse-grained exports beat dozens of tiny functions called in tight loops.

Testing strategy?

Unit test logic on native target; wasm-bindgen-test for browser-specific code.

WASI in production?

Growing for edge and plugins. Confirm runtime support before betting the architecture.

Component model now?

Adopt for new polyglot plugin boundaries; keep wasm-bindgen for existing browser apps.

Memory limits?

Browser tabs cap WASM memory. Stream large data instead of loading entirely into linear memory.

Debugging production?

Structured logging to host console; source maps in staging only.

Versioning WASM API?

Semver npm package; breaking export changes bump major version.

Accessibility?

If UI is WASM-rendered, manage focus and ARIA like any SPA framework.

WebAssembly Basics - fundamentals
Performance & Size - optimization techniques
wasm-bindgen - interop patterns
wasm-pack & Bundling - shipping workflow

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

WebAssembly Best Practices

Rules for WASM modules with clear interop boundaries and minimal payload size.

How to Use This List

Apply before shipping WASM to production browsers or edge runtimes
Treat every JS boundary crossing as a performance and ABI contract
Measure wasm file size gzipped, not just raw bytes

A - Boundary Design

Batch work per exported function. Amortize JS/WASM call overhead.
Return owned data. Prefer Vec<u8> / String over long-lived borrows.
Map errors to host types. Result<JsValue, JsValue> in browsers; integer codes in WASI.
Avoid panics in exports. Use console_error_panic_hook in dev only.

B - Size and Build

Release profile tuned for size. opt-level = "s", LTO, panic = "abort".
Run wasm-opt in CI. Track size regressions on every merge.
Minimal web-sys features. Enable only APIs you import.
Audit dependency tree. default-features = false where possible.

C - Runtime Behavior

Await init() before calls. Document startup in README and TS types.
Respect single-thread default. Use threads only when SharedArrayBuffer is available.
Preallocate buffers. Reduce WASM memory growth in hot loops.
Serve correct MIME type. application/wasm with compression.

D - Security and Ops

Validate all host input. Treat JS strings and byte slices as untrusted.
CSP compatible loading. Avoid eval; use module imports.
Pin toolchain versions. wasm-bindgen, wasm-pack, and Rust channel in CI.
Source maps for dev only. Do not ship full debug symbols to prod CDN.

E - Architecture Choices

Rust for compute, JS for DOM glue. Unless team commits to Leptos/Yew fully.
Choose target deliberately. wasm32-unknown-unknown vs wasm32-wasi vs components.
Fallback path. Graceful degradation when WASM fails to load.
SSR when SEO matters. Client-only WASM pages index poorly.

FAQs

When is WASM worth it?

CPU-heavy, portable logic: parsers, crypto, simulations, image/audio codecs.

Maximum module size?

Keep auxiliary modules under ~100 KB gzipped; split larger apps into lazy chunks.

How many exports?

Few coarse-grained exports beat dozens of tiny functions called in tight loops.

Testing strategy?

Unit test logic on native target; wasm-bindgen-test for browser-specific code.

WASI in production?

Growing for edge and plugins. Confirm runtime support before betting the architecture.

Component model now?

Adopt for new polyglot plugin boundaries; keep wasm-bindgen for existing browser apps.

Memory limits?

Browser tabs cap WASM memory. Stream large data instead of loading entirely into linear memory.

Debugging production?

Structured logging to host console; source maps in staging only.

Versioning WASM API?

Semver npm package; breaking export changes bump major version.

Accessibility?

If UI is WASM-rendered, manage focus and ARIA like any SPA framework.

WebAssembly Basics - fundamentals
Performance & Size - optimization techniques
wasm-bindgen - interop patterns
wasm-pack & Bundling - shipping workflow

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

WebAssembly Best Practices

Search Documentation

WebAssembly Best Practices