Rust WebAssembly

Build and verify Rust for the exact WebAssembly host that runs it. A .wasm suffix does not define an ABI, an import set, or a runtime.

Related skills, when installed: cargo-workflows for features and profiles, rust-async-internals for executor-independent futures, rust-performance and rust-hot-path for a measured hotspot. This skill owns the host event loop, WebAssembly limits, artifact size, and boundary costs.

Write the host contract first

When you add a WebAssembly target, a host, or a published package, record these facts. They decide the target, the dependencies, and the test matrix:

1. Name the Rust target triple.
2. Name the host and its minimum version.
3. Name the artifact format: core module or component.
4. List allowed imports and capabilities.
5. Name the JavaScript output mode when JavaScript glue exists.
6. Name the engine feature baseline: the WebAssembly features that the oldest supported engine accepts.

Do not infer the host from target_arch = "wasm32". Browser, Node.js, WASIp1, and WASIp2 builds can share that architecture and still have incompatible APIs.

Select the target

Do not use wasm32-unknown-unknown as a generic WASI target. It deliberately has no WASI imports. Do not send a WASIp2 component to an API that accepts only a core module.

The std targets do not emit WebAssembly 1.0 code. They enable multivalue, mutable-globals, reference-types, and sign-ext by default, and bulk-memory and nontrapping-fptoint since Rust 1.87 (LLVM 20). An engine without one of these features can reject the module. For a 1.0 engine, use wasm32v1-none on stable, or rebuild std for the MVP on nightly. Read references/target-setup.md when the engine baseline is older than these defaults or the MSRV is below 1.87.

Do not enable a WebAssembly target feature only because the compiler accepts it. The final module can contain those instructions even when a runtime path does not execute them. Gate optional SIMD code with #[cfg(target_feature = "simd128")] and keep a portable implementation.

Install each target with rustup target add <triple>. Rust 1.84 removed the wasm32-wasi name, so that command fails for it. Rename it to wasm32-wasip1 in CI, .cargo/config.toml, and rust-toolchain.toml.

Triage

Verify the matrix that ships

Use four layers. Stop only when all applicable layers pass.

1. Run portable logic on the host with cargo nextest run --locked, or cargo test --locked when cargo-nextest is not installed.
2. Compile every supported target and feature set.
3. Run boundary tests in each real host mode.
4. Load the final packaged artifact from the JavaScript package or deployment directory, not from Cargo's target directory.

Browser and Node.js tests:

wasm-pack test --headless --chrome
wasm-pack test --headless --firefox
wasm-pack test --node

Do not replace browser tests with Node.js tests. Node.js has no DOM and uses a different module loader. Do not replace runtime execution with cargo check --target; it does not instantiate the module or resolve imports.

Add one JavaScript integration test that imports the generated package, awaits initialization when required, calls a success path, and verifies the public error shape and any 64-bit value round trip. This catches stale glue, wrong package metadata, and a missing .wasm deployment asset.

Build an explicit matrix in CI. Include the target, Cargo features, host, and minimum host version in each row. Use cargo tree --locked --target <triple> -e features to find an additive Cargo feature that leaks an unsupported dependency into a row.

Validate each final artifact against the engine baseline. Plain wasm-tools validate accepts every phase 4 proposal, so it proves nothing about an old engine. wasm2 includes SIMD; append ,-simd when the baseline has no SIMD. A wasm1 or wasm2 group replaces the whole feature set and turns off the component model, so for a component add ,component-model.

wasm-tools validate --features=wasm2 pkg/<name>_bg.wasm   # WebAssembly 2.0 engine
wasm-tools validate --features=wasm1 pkg/<name>_bg.wasm   # WebAssembly 1.0 engine
wasm-tools validate --features=wasm2,component-model target/wasm32-wasip2/release/<binary>.wasm
wasm-tools print pkg/<name>_bg.wasm | grep '(import '     # compare with the host contract

Read references/wasi.md when a matrix row targets wasm32-wasip1 or wasm32-wasip2. It has the build, validate, and wasmtime run commands. Grant a WASI run only the directories, environment variables, sockets, and other host capabilities that it needs. A run with broad inherited access does not prove the production capability policy. Pin the WIT package versions and the host runtime together. A component can validate and still fail against a different world or interface version.

Run the checks again after a toolchain bump, a dependency bump, or a wasm-opt change. Load the module in the oldest supported engine when the contract names one.

Measure the final packaged .wasm, raw and gzip-compressed, against a size budget. Pin the wasm-pack version and the wasm-opt that it runs: a wasm-pack upgrade can silently change the bundled optimizer. Read references/size-and-optimizer.md when you set a size budget, change the release profile, or change how wasm-opt runs.

Completion evidence

Report:

• the target, host, minimum version, artifact type, and capability policy;
• the exact Cargo feature set and the engine feature baseline;
• the build, validation, and runtime commands for every shipped matrix row, including the wasm-tools validate --features=... baseline check and the import list of each final artifact;
• a successful import of the final JavaScript package when JS glue exists;
• raw and compressed artifact sizes against the budget;
• any browser, Node.js, WASI, or component row that could not run.

Keep portable logic separate

Put parsing, validation, state transitions, and business rules in a normal Rust library. Put browser, Node.js, and WASI adapters at the edge.

Use target predicates only for facts that the compiler knows: cfg(all(target_family = "wasm", target_os = "unknown")) for a bare JavaScript host, and cfg(all(target_os = "wasi", target_env = "p1")) or target_env = "p2" for a WASI preview. Rust cannot detect browser against Node.js with cfg. If the same crate ships to both, select adapters with explicit Cargo features and reject invalid feature sets. Keep one neutral default when possible.

#[cfg(all(feature = "browser", feature = "node"))]
compile_error!("select only one JavaScript host feature");

fn main() {}

Target-specific dependency tables stop browser-only crates from entering WASI resolution:

[target.'cfg(all(target_family = "wasm", target_os = "unknown"))'.dependencies]
wasm-bindgen = "0.2"
js-sys = "0.3"

[target.'cfg(all(target_family = "wasm", target_os = "unknown"))'.dependencies.web-sys]
version = "0.3"
features = ["Window", "Performance", "console"]

Enable only the web-sys interfaces that the code uses. Each one adds binding code, compile time, and possible artifact size.

Inject the clock. On wasm32-unknown-unknown, read time in the JavaScript adapter and pass it to the portable code, because std::time panics there. Use js_sys::Date::now(), or window.performance() and then .now() on the result. now is an instance method of web_sys::Performance, so write web_sys::window().and_then(|w| w.performance()).map(|p| p.now()). It needs the Window and Performance features.

getrandom has no default backend on wasm32-unknown-unknown. Enable feature wasm_js (0.3.4 and later, 0.4) or js (0.2) for each major version in the graph. Set it in the final cdylib or binary crate, not in a library: upstream warns that it breaks non-JavaScript WebAssembly builds. Read references/target-setup.md when the graph holds getrandom 0.3.0 to 0.3.3 or more than one major version.

Build for a JavaScript host

Read references/javascript-host.md when the crate exports to a browser or Node.js through wasm-bindgen: it has the crate type, the wasm-pack output modes, the CLI version rule, and initialization.

Design the JavaScript boundary

Read references/javascript-host.md when you design exports, imports, callbacks, or error values that cross the JavaScript boundary.

Handle panic and error behavior

Read references/panic-and-errors.md when you choose the panic strategy, install a panic hook, or decide whether an instance survives a trap.

Use the host async model

Read references/async-hosts.md when the code awaits a JavaScript Promise, spawns a future, uses Tokio or threads, or does async I/O on WASI.

Build WASI artifacts

Read references/wasi.md when you ship a WASI component or compile C or C++ for a WASI target.