wasm-bindgen

Bridge Rust and JavaScript with wasm-bindgen macros and glue code generation.

Recipe

use wasm_bindgen::prelude::*;
 
#[wasm_bindgen]
pub fn greet(name: &str) -> String {
    format!("Hello, {name}!")
}

wasm-pack build --target web

When to reach for this: Browser WASM that must call JS APIs and expose Rust functions to JavaScript.

Working Example

use wasm_bindgen::prelude::*;
use serde::{Deserialize, Serialize};
 
#[wasm_bindgen]
pub struct Counter {
    value: u32,
}
 
#[wasm_bindgen]
impl Counter {
    #[wasm_bindgen(constructor)]
    pub fn new() -> Counter {
        Counter { value: 0 }
    }
 
    pub fn increment(&mut self) {
        self.value += 1;
    }
 
    pub fn value(&self) -> u32 {
        self.value
    }
}
 
#[wasm_bindgen]
pub fn parse_json(input: &str) -> Result<JsValue, JsValue> {
    let data: serde_json::Value = serde_json::from_str(input)
        .map_err(|e| JsValue::from_str(&e.to_string()))?;
    Ok(JsValue::from_serde(&data)?)
}

import init, { Counter, parse_json } from "./pkg/mylib.js";
 
await init();
const c = new Counter();
c.increment();
console.log(c.value());
console.log(parse_json('{"ok":true}'));

What this demonstrates:

• #[wasm_bindgen] exports Rust types to JS classes
• constructor maps to new Counter()
• JsValue crosses the boundary for dynamic JSON
• wasm-pack generates TypeScript-friendly JS wrappers

Deep Dive

Type Mapping

Importing JS

#[wasm_bindgen]
extern "C" {
    fn alert(s: &str);
    #[wasm_bindgen(js_namespace = console)]
    fn log(s: &str);
}

Gotchas

• Ownership across boundary - JS may retain references unpredictably. Fix: Prefer owned returns (String, Vec) over long-lived borrows.
• Panic in exported fn - Crashes the WASM instance. Fix: Return Result<JsValue, JsValue> to JS.
• Non-Send types in async - wasm-bindgen-futures requires Send futures. Fix: Use spawn_local for DOM futures.
• serde and JsValue - from_serde needs serde-wasm-bindgen in modern stacks. Fix: Use serde-wasm-bindgen for performance.
• Debug vs release size - Debug WASM is huge. Fix: Always --release for browser deploys.

Alternatives

FAQs

Related

• WebAssembly Basics - targets and builds
• wasm-pack & Bundling - shipping npm packages
• DOM & Web APIs (web-sys) - browser APIs
• Performance & Size - shrinking binaries

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+.