Calling Rust from JavaScript

23 min read

Quick Overview

Once you compile a Rust crate to WebAssembly with #[wasm_bindgen], the functions and structs you mark pub become real JavaScript values: an exported function turns into a JS function, and an exported struct turns into a JS class with methods, getters, and a constructor. This page is about the consumer side of that boundary: what your exports look like from JavaScript or TypeScript, the JS “glue” code wasm-bindgen generates to make it work, and the rules a TypeScript developer needs to internalize so the experience feels like calling any other module.

Note: The current stable toolchain is Rust 1.96.0 on the latest stable edition (2024); cargo new selects it automatically. The examples here target wasm-bindgen 0.2 (resolved to 0.2.122 at the time of writing) on the wasm32-unknown-unknown target. This page assumes you already have a project building — see Setting Up wasm-pack and Your First Rust to WASM Module. The opposite direction (calling JS from Rust) is covered in Calling JavaScript from Rust, and the fine details of which types can cross the boundary live in the wasm-bindgen Deep Dive.

TypeScript/JavaScript Example

Here is the kind of thing you would reach for a library to do: a small analytics module. In a pure-TypeScript world you would publish it as an npm package and import it.

1
// analytics.ts — a hand-written TypeScript module
2
export function mean(values: number[]): number {
3
  if (values.length === 0) return NaN;
4
  return values.reduce((a, b) => a + b, 0) / values.length;
5
}
6

7
export function formatCurrency(amount: number): string {
8
  return `$${amount.toFixed(2)}`;
9
}
10

11
// A class with state, a constructor, methods, and a read-only property.
12
export class Histogram {
13
  private buckets: Uint32Array;
14
  private readonly bucketWidth: number;
15

16
  constructor(bucketCount: number, bucketWidth: number) {
17
    this.buckets = new Uint32Array(bucketCount);
18
    this.bucketWidth = bucketWidth;
19
  }
20

21
  record(value: number): void {
22
    const idx = Math.min(
23
      Math.floor(value / this.bucketWidth),
24
      this.buckets.length - 1,
25
    );
26
    this.buckets[idx] += 1;
27
  }
28

29
  get total(): number {
30
    return this.buckets.reduce((a, b) => a + b, 0);
31
  }
32

33
  counts(): Uint32Array {
34
    return this.buckets.slice();
35
  }
36
}

A caller imports it and uses it exactly as you would expect:

1
import { mean, formatCurrency, Histogram } from "./analytics";
2

3
console.log(mean([10, 20, 30])); // 20
4
console.log(formatCurrency(19.5)); // "$19.50"
5

6
const hist = new Histogram(4, 25);
7
hist.record(10);
8
hist.record(60);
9
console.log(hist.total); // 2 — a property, no parentheses
10
console.log(hist.counts()); // Uint32Array(4) [ 1, 0, 1, 0 ]

Two things to hold onto, because they shape everything that follows: the class manages its own memory through the garbage collector (you never free a Histogram), and total is a property you read without calling it.

Rust Equivalent

The same module written in Rust and exported with #[wasm_bindgen]. The crate is a library compiled to the cdylib crate type (see Setting Up wasm-pack for the Cargo.toml).

1
use wasm_bindgen::prelude::*;
2

3
/// A free function. Becomes an exported JS function `mean(values)`.
4
#[wasm_bindgen]
5
pub fn mean(values: &[f64]) -> f64 {
6
    if values.is_empty() {
7
        return f64::NAN;
8
    }
9
    values.iter().sum::<f64>() / values.len() as f64
10
}
11

12
/// Rename on the JS side: callable as `formatCurrency(...)` in JS,
13
/// while staying idiomatic snake_case in Rust.
14
#[wasm_bindgen(js_name = formatCurrency)]
15
pub fn format_currency(amount: f64) -> String {
16
    format!("${amount:.2}")
17
}
18

19
/// A struct exported as a JS class.
20
#[wasm_bindgen]
21
pub struct Histogram {
22
    buckets: Vec<u32>,
23
    bucket_width: f64,
24
}
25

26
#[wasm_bindgen]
27
impl Histogram {
28
    /// Exported as the JS constructor: `new Histogram(bucketCount, bucketWidth)`.
29
    #[wasm_bindgen(constructor)]
30
    pub fn new(bucket_count: usize, bucket_width: f64) -> Histogram {
31
        Histogram {
32
            buckets: vec![0; bucket_count],
33
            bucket_width,
34
        }
35
    }
36

37
    /// A method: `histogram.record(value)`.
38
    pub fn record(&mut self, value: f64) {
39
        let idx = (value / self.bucket_width) as usize;
40
        let last = self.buckets.len() - 1;
41
        let idx = idx.min(last);
42
        self.buckets[idx] += 1;
43
    }
44

45
    /// A getter: read as `histogram.total` (no parentheses) from JS.
46
    #[wasm_bindgen(getter)]
47
    pub fn total(&self) -> u32 {
48
        self.buckets.iter().sum()
49
    }
50

51
    /// Returns owned data; the bytes are copied into a JS `Uint32Array`.
52
    pub fn counts(&self) -> Vec<u32> {
53
        self.buckets.clone()
54
    }
55
}

Building this with wasm-pack build --target web produces a pkg/ directory whose .d.ts declares the exports. This is the real, generated TypeScript surface — not something hand-written:

1
// pkg/analytics.d.ts (generated by wasm-bindgen)
2
/* tslint:disable */
3
/* eslint-disable */
4

5
/**
6
 * A struct exported as a JS class.
7
 */
8
export class Histogram {
9
    free(): void;
10
    [Symbol.dispose](): void;
11
    /**
12
     * Returns owned data; the bytes are copied into a JS `Uint32Array`.
13
     */
14
    counts(): Uint32Array;
15
    /**
16
     * Exported as the JS constructor: `new Histogram(bucketCount, bucketWidth)`.
17
     */
18
    constructor(bucket_count: number, bucket_width: number);
19
    /**
20
     * A method: `histogram.record(value)`.
21
     */
22
    record(value: number): void;
23
    /**
24
     * A getter: read as `histogram.total` (no parentheses) from JS.
25
     */
26
    readonly total: number;
27
}
28

29
/**
30
 * Rename on the JS side: callable as `formatCurrency(...)` in JS,
31
 * while staying idiomatic snake_case in Rust.
32
 */
33
export function formatCurrency(amount: number): string;
34

35
/**
36
 * A free function. Becomes an exported JS function `mean(values)`.
37
 */
38
export function mean(values: Float64Array): number;

Notice that the generated declarations match the TypeScript module almost exactly: mean returns a number, Histogram is a class with a constructor, record is a method, and total is readonly (a getter). Each /// doc comment is carried through as a JSDoc block on the corresponding declaration. The two extra members — free() and [Symbol.dispose]() — are the memory-management hook that has no TypeScript equivalent. More on that below.

Detailed Explanation

Free functions become exported functions

#[wasm_bindgen] on a pub fn does two jobs. First, it tells the compiler to keep the function in the final .wasm binary and expose it as a WebAssembly export. Second — and this is the part that matters for JavaScript callers — it generates a JavaScript wrapper that translates arguments and return values across the boundary. WebAssembly itself only understands integers and floats, so anything richer (a string, a slice, a struct) needs glue.

Here is the actual generated wrapper for mean:

1
// pkg/analytics.js (generated) — the wrapper for `mean`
2
export function mean(values) {
3
    const ptr0 = passArrayF64ToWasm0(values, wasm.__wbindgen_malloc);
4
    const len0 = WASM_VECTOR_LEN;
5
    const ret = wasm.mean(ptr0, len0);
6
    return ret;
7
}

The Rust signature mean(values: &[f64]) became a JS function that takes a Float64Array. The glue copies the array’s bytes into the WebAssembly linear memory (passArrayF64ToWasm0), then calls the raw exported function wasm.mean(ptr, len) with a pointer and length — exactly the two integers WebAssembly can actually pass. Your Rust code receives a normal &[f64] slice and never sees any of this.

format_currency shows the same pattern for strings. The wrapper allocates space in WebAssembly memory, calls the function, then reads the resulting String back out and frees it:

1
// pkg/analytics.js (generated) — the wrapper for `formatCurrency`
2
export function formatCurrency(amount) {
3
    let deferred1_0;
4
    let deferred1_1;
5
    try {
6
        const ret = wasm.formatCurrency(amount);
7
        deferred1_0 = ret[0];
8
        deferred1_1 = ret[1];
9
        return getStringFromWasm0(ret[0], ret[1]);
10
    } finally {
11
        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
12
    }
13
}

Tip: The #[wasm_bindgen(js_name = formatCurrency)] attribute renames the export. Rust convention is snake_case for functions, JavaScript convention is camelCase. Without the rename, JS callers would have to write format_currency, which looks out of place in a JS/TS codebase. Renaming keeps both sides idiomatic.

Structs become JS classes

A pub struct annotated with #[wasm_bindgen] becomes a JavaScript class. The Rust value lives in WebAssembly’s linear memory; the JS object is a thin handle that holds a pointer to it. Here is the generated class:

1
// pkg/analytics.js (generated) — the Histogram class
2
export class Histogram {
3
    __destroy_into_raw() {
4
        const ptr = this.__wbg_ptr;
5
        this.__wbg_ptr = 0;
6
        HistogramFinalization.unregister(this);
7
        return ptr;
8
    }
9
    free() {
10
        const ptr = this.__destroy_into_raw();
11
        wasm.__wbg_histogram_free(ptr, 0);
12
    }
13
    counts() {
14
        const ret = wasm.histogram_counts(this.__wbg_ptr);
15
        var v1 = getArrayU32FromWasm0(ret[0], ret[1]).slice();
16
        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
17
        return v1;
18
    }
19
    constructor(bucket_count, bucket_width) {
20
        const ret = wasm.histogram_new(bucket_count, bucket_width);
21
        this.__wbg_ptr = ret;
22
        HistogramFinalization.register(this, this.__wbg_ptr, this);
23
        return this;
24
    }
25
    record(value) {
26
        wasm.histogram_record(this.__wbg_ptr, value);
27
    }
28
    get total() {
29
        const ret = wasm.histogram_total(this.__wbg_ptr);
30
        return ret >>> 0;
31
    }
32
}
33
if (Symbol.dispose) Histogram.prototype[Symbol.dispose] = Histogram.prototype.free;

Reading this top to bottom tells the whole story:

this.__wbg_ptr is the pointer to the Rust Histogram inside WebAssembly memory. Every method passes it as the first argument to the raw export (wasm.histogram_record(this.__wbg_ptr, value)). This is exactly how &self/&mut self is implemented across the boundary.
The constructor calls wasm.histogram_new(...), stores the returned pointer, and registers the object with a FinalizationRegistry.
get total() is generated from the #[wasm_bindgen(getter)] method, so JS reads hist.total with no parentheses. The >>> 0 coerces the value to an unsigned 32-bit integer (Rust’s u32).
counts() reads a Vec<u32> back out of WebAssembly memory into a fresh JS Uint32Array and frees the temporary Rust allocation.

Memory: the `free()` method and `FinalizationRegistry`

This is the single biggest conceptual difference from a hand-written TypeScript class, so it is worth slowing down. In JavaScript, the garbage collector owns every object; you never deallocate manually. But the actual Histogram data lives in WebAssembly’s linear memory, which the JS garbage collector does not manage. So the Rust value has to be freed explicitly when the JS handle goes away.

wasm-bindgen handles this two ways:

A FinalizationRegistry (a standard JS API since 2021) is wired up so that if the JS garbage collector eventually collects the handle, a callback runs __wbg_histogram_free to release the Rust memory. This is a safety net, not a guarantee — finalizers run “eventually, maybe.”
An explicit free() method (and, in modern output, [Symbol.dispose], so it works with the TC39 using declaration) lets you release the memory deterministically the moment you are done.

1
// Deterministic cleanup with the `using` declaration (TypeScript 5.2+)
2
import init, { Histogram } from "./pkg/analytics.js";
3

4
await init();
5

6
{
7
  using hist = new Histogram(4, 25); // [Symbol.dispose] === free
8
  hist.record(10);
9
  console.log(hist.total);
10
} // hist.free() runs automatically here

Warning: Relying solely on the FinalizationRegistry can leak WebAssembly memory in long-running apps, because finalizers are not prompt and not guaranteed to run at all. For short-lived objects this is fine; for objects you create in a hot loop, call free() (or use using) explicitly.

How a JavaScript caller wires it up

With the web target, the generated module is an ES module with a default export that loads and instantiates the .wasm file. You must await initialization before calling anything:

1
// app.ts — consuming the `web`-target build
2
import init, { mean, formatCurrency, Histogram } from "./pkg/analytics.js";
3

4
async function main() {
5
  await init(); // fetch + instantiate analytics_bg.wasm — required first
6

7
  console.log(mean(new Float64Array([10, 20, 30]))); // 20
8
  console.log(formatCurrency(19.5)); // "$19.50"
9

10
  const hist = new Histogram(4, 25);
11
  hist.record(10);
12
  hist.record(60);
13
  console.log(hist.total); // 2
14
  console.log(hist.counts()); // Uint32Array(4) [ 1, 0, 1, 0 ]
15
  hist.free();
16
}
17

18
main();

The await init() step is the one piece with no TypeScript-module analogue. JavaScript modules are ready to use the moment they are imported; a WebAssembly module has to be fetched and instantiated first, which is asynchronous. Forgetting await init() is the most common first-time mistake (see Common Pitfalls).

Key Differences

Aspect	Hand-written TypeScript module	Rust compiled with `#[wasm_bindgen]`
Exported function	`export function f(...)`	`#[wasm_bindgen] pub fn f(...)`
Exported class	`export class C`	`#[wasm_bindgen] pub struct C` + `impl` block
Constructor	`constructor(...)`	method tagged `#[wasm_bindgen(constructor)]`
Getter	`get x()`	method tagged `#[wasm_bindgen(getter)]`
Naming	`camelCase` everywhere	`snake_case` in Rust, `#[wasm_bindgen(js_name=...)]` to rename
Memory	GC-managed, invisible	handle + pointer; needs `free()` or `using`
Initialization	ready on `import`	must `await init()` first (web/bundler targets)
Generics	erased at runtime	not allowed on exports; must be concrete
Errors	`throw` anything	`Result<T, JsError>` → thrown JS `Error`
`number[]` arg	a real JS array	maps to a typed array (`Float64Array`, etc.)

The deepest difference is ownership crossing a language boundary. In TypeScript, every value is owned by the JS runtime. With WebAssembly, an exported struct is owned by Rust and merely referenced by a JS handle. That is why a Histogram has a free() method and a plain TS class does not, and why methods that return collections (counts()) hand you a copy rather than a live view — the underlying Vec<u32> belongs to Rust.

A second difference worth flagging: TypeScript generics are erased at compile time and have no runtime cost, so function identity<T>(x: T): T is perfectly normal. A generic Rust function cannot be exported, because there is no single concrete machine-code function to expose — WebAssembly needs a monomorphized, concrete signature. You must pick concrete types at the boundary.

Error handling crosses as exceptions

Returning a Result<T, E> where E: Into<JsValue> (the simplest being JsError) turns the Err arm into a thrown JavaScript exception, and the Ok arm into the plain return value. The generated TypeScript type shows only the success type — the throwing is invisible in the type, just like any TS function that can throw:

1
use wasm_bindgen::prelude::*;
2

3
/// The `Err` arm becomes a thrown JS exception; the `Ok` arm is the return value.
4
#[wasm_bindgen(js_name = parsePercentage)]
5
pub fn parse_percentage(input: &str) -> Result<f64, JsError> {
6
    let trimmed = input.trim().trim_end_matches('%');
7
    let value: f64 = trimmed
8
        .parse()
9
        .map_err(|_| JsError::new(&format!("not a number: {input:?}")))?;
10
    if !(0.0..=100.0).contains(&value) {
11
        return Err(JsError::new("percentage must be between 0 and 100"));
12
    }
13
    Ok(value / 100.0)
14
}

The generated declaration is just export function parsePercentage(input: string): number; — note the : number, with no hint of the error path. From JavaScript you handle it with an ordinary try/catch:

1
import init, { parsePercentage } from "./pkg/analytics.js";
2
await init();
3

4
console.log(parsePercentage("42%")); // 0.42
5
try {
6
  parsePercentage("nope");
7
} catch (e) {
8
  console.log((e as Error).message); // 'not a number: "nope"'
9
}

Running this exact module under Node (built with --target nodejs) produces real output:

1
parsePercentage('42%'): 0.42
2
threw: not a number: "nope"
3
threw: percentage must be between 0 and 100

The Rust error message survives the crossing intact as the JS Error.message. For a thorough treatment of richer error values and JsValue, see the wasm-bindgen Deep Dive.

Common Pitfalls

Pitfall 1: Trying to export a generic function

Coming from TypeScript, writing a generic helper feels natural. It does not compile when exported:

1
use wasm_bindgen::prelude::*;
2

3
#[wasm_bindgen]
4
pub fn largest<T: PartialOrd>(a: T, b: T) -> T { // does not compile
5
    if a > b { a } else { b }
6
}

The compiler is explicit about why:

1
error: can't #[wasm_bindgen] functions with lifetime or type parameters
2
 --> src/lib.rs:4:15
3
  |
4
4 | pub fn largest<T: PartialOrd>(a: T, b: T) -> T {

Fix: pick a concrete type at the boundary (pub fn largest(a: f64, b: f64) -> f64). You can keep an internal generic helper and export a concrete wrapper that calls it.

Pitfall 2: A public, non-`Copy` field on an exported struct

wasm-bindgen generates a getter and a setter for each pub field of an exported struct. By default the getter returns the value, which requires the field to be Copy. A String is not Copy:

1
use wasm_bindgen::prelude::*;
2

3
#[wasm_bindgen]
4
pub struct User {
5
    pub id: u32,
6
    pub name: String, // does not compile
7
}

The real error:

1
error[E0277]: the trait bound `String: std::marker::Copy` is not satisfied
2
 --> src/lib.rs:6:15
3
  |
4
3 | #[wasm_bindgen]
5
  | --------------- in this procedural macro expansion
6
...
7
6 |     pub name: String,  // non-Copy public field
8
  |               ^^^^^^ the trait `std::marker::Copy` is not implemented for `String`
9
  |
10
note: required by a bound in `__wbg_get_user_name::assert_copy`

Fix: add getter_with_clone so the generated getter clones the field instead of copying it. This compiles cleanly:

1
use wasm_bindgen::prelude::*;
2

3
#[wasm_bindgen(getter_with_clone)]
4
pub struct User {
5
    pub id: u32,
6
    pub name: String, // now exported via a cloning getter/setter
7
}

Pitfall 3: Using a handle after `free()` (or after `using` scope ends)

Because the Rust value is freed but the JS handle object still exists, calling a method on a freed handle is a use-after-free. It does not crash silently — wasm-bindgen detects the null pointer and throws:

1
const stats = new TextStats("hello world");
2
stats.free();
3
console.log(stats.wordCount); // throws

The real runtime error (captured running the module in Node):

1
Error: null pointer passed to rust
2
    at __wbg___wbindgen_throw_... (analytics.js:39:19)
3
    at wasm://wasm/a50b6c42:wasm-function[43]:0x3206

Fix: do not touch a handle after free(). With the using declaration, watch out for the same trap: the object is freed at the end of the block, so do not stash a reference that outlives the block.

Note: This also bites you when you pass a struct by value into another exported function. Moving a value into Rust consumes the JS handle (its pointer is zeroed), so the original JS variable becomes a freed handle. If you need to keep using it afterward, take &self instead of self on the Rust side.

Pitfall 4: Forgetting `await init()`

With the web and bundler targets, the .wasm must be instantiated before any export works. Calling an export first throws a TypeError about reading a property of undefined (the glue’s wasm binding is still unset). Always await init() (web target) or import from a bundler-aware entry that does it for you. The nodejs target is the exception: it instantiates synchronously at require time using fs.readFileSync, so there is no init step.

Best Practices

Rename exports to camelCase. Use #[wasm_bindgen(js_name = doThing)] on functions and methods, and js_name/js_class on structs, so the JavaScript API reads like a normal JS API. Keep snake_case in your Rust source.
Prefer &self/&mut self methods over consuming self unless you genuinely want to hand ownership to the caller’s call. Consuming self invalidates the JS handle, which surprises JS callers.
Expose deterministic cleanup. Document that long-lived exported objects should be free()d or wrapped in using. The FinalizationRegistry is a safety net, not a memory-management strategy.
Return owned data, not borrowed. You cannot return a &str or &[T] that borrows from self across the boundary, because the JS side has no lifetime to anchor it to. Return String/Vec<T> (a copy) or expose a getter.
Use Result<T, JsError> for fallible exports so JS callers get idiomatic try/catch instead of sentinel return values.
Let wasm-pack generate the .d.ts. The generated TypeScript declarations are accurate and free; commit them or publish them with your npm package so TS consumers get full type-checking. See Deploying WASM Apps for packaging.
Keep the boundary coarse. Each call across the JS↔WASM boundary has overhead (argument marshalling, memory copies). Prefer one call that does a lot of work over many small calls in a tight loop — see WASM Performance.

Real-World Example

A text-analysis engine you might ship as an npm package: a stateful TextStats class plus a fallible parser. This is the complete crate, and every snippet here was compiled to wasm32-unknown-unknown and exercised from Node.

1
use wasm_bindgen::prelude::*;
2

3
/// A reusable text-analysis engine, exported to JS as a class.
4
#[wasm_bindgen]
5
pub struct TextStats {
6
    text: String,
7
}
8

9
#[wasm_bindgen]
10
impl TextStats {
11
    #[wasm_bindgen(constructor)]
12
    pub fn new(text: String) -> TextStats {
13
        TextStats { text }
14
    }
15

16
    /// Read-only property: `stats.wordCount`.
17
    #[wasm_bindgen(getter, js_name = wordCount)]
18
    pub fn word_count(&self) -> usize {
19
        self.text.split_whitespace().count()
20
    }
21

22
    #[wasm_bindgen(getter, js_name = charCount)]
23
    pub fn char_count(&self) -> usize {
24
        self.text.chars().count()
25
    }
26

27
    /// Returns the N most frequent words as a JS array of strings.
28
    #[wasm_bindgen(js_name = topWords)]
29
    pub fn top_words(&self, n: usize) -> Vec<String> {
30
        use std::collections::HashMap;
31
        let mut counts: HashMap<&str, u32> = HashMap::new();
32
        for word in self.text.split_whitespace() {
33
            *counts.entry(word).or_insert(0) += 1;
34
        }
35
        let mut pairs: Vec<(&str, u32)> = counts.into_iter().collect();
36
        // Most frequent first; break ties alphabetically for stable output.
37
        pairs.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(b.0)));
38
        pairs
39
            .into_iter()
40
            .take(n)
41
            .map(|(w, _)| w.to_string())
42
            .collect()
43
    }
44
}
45

46
/// A free function that can fail; the `Err` becomes a thrown JS exception.
47
#[wasm_bindgen(js_name = parsePercentage)]
48
pub fn parse_percentage(input: &str) -> Result<f64, JsError> {
49
    let trimmed = input.trim().trim_end_matches('%');
50
    let value: f64 = trimmed
51
        .parse()
52
        .map_err(|_| JsError::new(&format!("not a number: {input:?}")))?;
53
    if !(0.0..=100.0).contains(&value) {
54
        return Err(JsError::new("percentage must be between 0 and 100"));
55
    }
56
    Ok(value / 100.0)
57
}

The generated .d.ts is the public TypeScript contract — note that each /// doc comment becomes a JSDoc block on the corresponding declaration (members without a doc comment, such as the constructor and charCount here, simply get none), usize becomes number, and Vec<String> becomes string[]:

1
// pkg/analytics.d.ts (generated)
2
/**
3
 * A reusable text-analysis engine, exported to JS as a class.
4
 */
5
export class TextStats {
6
    free(): void;
7
    [Symbol.dispose](): void;
8
    constructor(text: string);
9
    /**
10
     * Returns the N most frequent words as a JS array of strings.
11
     */
12
    topWords(n: number): string[];
13
    readonly charCount: number;
14
    /**
15
     * Read-only property: `stats.wordCount`.
16
     */
17
    readonly wordCount: number;
18
}
19

20
/**
21
 * A free function that can fail; the `Err` becomes a thrown JS exception.
22
 */
23
export function parsePercentage(input: string): number;

Consuming it from a Node program (built with wasm-pack build --target nodejs):

1
const wasm = require("./pkg/analytics.js");
2

3
const stats = new wasm.TextStats("the quick brown fox the lazy dog the fox");
4
console.log("wordCount:", stats.wordCount);
5
console.log("charCount:", stats.charCount);
6
console.log("topWords(2):", stats.topWords(2));
7
stats.free();
8

9
console.log("parsePercentage('42%'):", wasm.parsePercentage("42%"));
10
try {
11
  wasm.parsePercentage("nope");
12
} catch (e) {
13
  console.log("threw:", e.message);
14
}

The real output from running it:

1
wordCount: 9
2
charCount: 40
3
topWords(2): [ 'the', 'fox' ]
4
parsePercentage('42%'): 0.42
5
threw: not a number: "nope"

Everything lines up with how the equivalent hand-written TypeScript class would behave — the only visible seam is the explicit stats.free().

Tip: The nodejs target instantiates the module synchronously at require time (its glue ends with require('fs').readFileSync(...) and a synchronous new WebAssembly.Instance(...)), so there is no await init(). The web and bundler targets are asynchronous. Pick the target that matches where the code runs — see Setting Up wasm-pack.

Exercises

Exercise 1: Export a counter class

Difficulty: Easy

Objective: Export a stateful struct as a JS class with a constructor, a mutating method, and a getter.

Instructions:

Create a Counter struct holding a single i32 count.
Add a constructor that takes a starting value (new Counter(start)).
Add an increment(&mut self, by: i32) method.
Add a value getter returning the current count.
Make sure the getter is read as counter.value (no parentheses) from JS.

1
use wasm_bindgen::prelude::*;
2

3
#[wasm_bindgen]
4
pub struct Counter {
5
    count: i32,
6
}
7

8
#[wasm_bindgen]
9
impl Counter {
10
    // TODO: constructor, increment, value getter
11
}

Solution

1
use wasm_bindgen::prelude::*;
2

3
#[wasm_bindgen]
4
pub struct Counter {
5
    count: i32,
6
}
7

8
#[wasm_bindgen]
9
impl Counter {
10
    #[wasm_bindgen(constructor)]
11
    pub fn new(start: i32) -> Counter {
12
        Counter { count: start }
13
    }
14

15
    pub fn increment(&mut self, by: i32) {
16
        self.count += by;
17
    }
18

19
    #[wasm_bindgen(getter)]
20
    pub fn value(&self) -> i32 {
21
        self.count
22
    }
23
}

From JavaScript:

1
const c = new Counter(10);
2
c.increment(5);
3
console.log(c.value); // 15
4
c.free();

This compiles cleanly for wasm32-unknown-unknown and the generated .d.ts declares constructor(start: number), increment(by: number): void, and readonly value: number.

Exercise 2: A fallible exported function

Difficulty: Medium

Objective: Export a function whose error path becomes a thrown JS exception.

Instructions:

Write divide(a: f64, b: f64) -> Result<f64, JsError>.
Return an Err(JsError::new(...)) when b == 0.0, otherwise Ok(a / b).
Confirm that from JS, divide(10, 2) returns 5 and divide(10, 0) throws an Error you can catch.
Rename it to safeDivide on the JS side.

Solution

1
use wasm_bindgen::prelude::*;
2

3
#[wasm_bindgen(js_name = safeDivide)]
4
pub fn safe_divide(a: f64, b: f64) -> Result<f64, JsError> {
5
    if b == 0.0 {
6
        return Err(JsError::new("division by zero"));
7
    }
8
    Ok(a / b)
9
}

From JavaScript:

1
console.log(safeDivide(10, 2)); // 5
2
try {
3
  safeDivide(10, 0);
4
} catch (e) {
5
  console.log(e.message); // "division by zero"
6
}

The generated declaration is export function safeDivide(a: number, b: number): number; — the throwing behaviour is real at runtime but, as with any throwing TS function, not visible in the return type.

Exercise 3: Avoid the use-after-move trap

Difficulty: Hard

Objective: Design an exported API that passes a struct between functions without invalidating the caller’s JS handle.

Instructions:

Export a Vector2 { x: f64, y: f64 } struct (use getter_with_clone is not needed here since the fields are f64, which is Copy — but feel free to expose x/y as pub).
Add a method add(&self, other: &Vector2) -> Vector2 that returns a new vector.
Crucially, take other by reference (&Vector2), not by value, so the caller’s handle stays usable.
From JS, create two vectors a and b, compute a.add(b), and confirm that b is still usable afterward (its x getter still works).

Solution

1
use wasm_bindgen::prelude::*;
2

3
#[wasm_bindgen]
4
pub struct Vector2 {
5
    pub x: f64,
6
    pub y: f64,
7
}
8

9
#[wasm_bindgen]
10
impl Vector2 {
11
    #[wasm_bindgen(constructor)]
12
    pub fn new(x: f64, y: f64) -> Vector2 {
13
        Vector2 { x, y }
14
    }
15

16
    // Borrow `other` so the caller's JS handle is NOT consumed.
17
    pub fn add(&self, other: &Vector2) -> Vector2 {
18
        Vector2 {
19
            x: self.x + other.x,
20
            y: self.y + other.y,
21
        }
22
    }
23
}

From JavaScript:

1
const a = new Vector2(1, 2);
2
const b = new Vector2(3, 4);
3
const c = a.add(b);
4
console.log(c.x, c.y); // 4 6
5
console.log(b.x);      // 3 — b is still alive because `add` borrowed it
6
a.free();
7
b.free();
8
c.free();

If add had taken other: Vector2 (by value), the call would have moved b into Rust and zeroed b.__wbg_ptr; the next b.x access would then throw Error: null pointer passed to rust. Taking &Vector2 keeps b owned by JavaScript. The fields x/y are f64 (which is Copy), so plain pub fields work without getter_with_clone.

Calling Rust from JavaScript

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Free functions become exported functions

Structs become JS classes

Memory: the free() method and FinalizationRegistry

How a JavaScript caller wires it up

Key Differences

Error handling crosses as exceptions

Common Pitfalls

Pitfall 1: Trying to export a generic function

Pitfall 2: A public, non-Copy field on an exported struct

Pitfall 3: Using a handle after free() (or after using scope ends)

Pitfall 4: Forgetting await init()

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Export a counter class

Exercise 2: A fallible exported function

Exercise 3: Avoid the use-after-move trap

Memory: the `free()` method and `FinalizationRegistry`

Pitfall 2: A public, non-`Copy` field on an exported struct

Pitfall 3: Using a handle after `free()` (or after `using` scope ends)

Pitfall 4: Forgetting `await init()`