Forem: Márk Tolmács

Building Elbow Arrows in Excalidraw (Part 2)

Márk Tolmács — Fri, 19 Dec 2025 12:55:29 +0000

Previously on Building Elbow Arrows...

In part one we identified the design goals (shortest route, minimal segments, proper arrow orientation and shape avoidance), but our naive and greedy first approach to the algorithm turned out to be inadequate on multiple fronts. Therefore this approach is abandoned in favor of a different algorithm.

Games to the Rescue

The design goals were suspiciously similar to the problem of pathfinding in video games, which is a common, well researched problem. Characters in these games often have to find their way from point A to point B on the game map, without getting blocked by obstacles and use the shortest route. They also need to make it look like a human would take that route, so these characters don't break the immersion. Thus, we turn out focus to A* search algorithm.

Building the Foundations

To understand A* pathfinding we need to understand the context, some of the other graph search algorithms it is built and improved on, and how can they help solve our challenge. To begin with, let's talk about where A* comes from. It is part of a family of algorithms for graph search, which all aim to find the shortest path in a graph of nodes connected by edges. While this makes them useful far beyond just games, we'll just focus on pathfinding in a 2D grid (i.e. the canvas). How do we convert the canvas into a graph you ask? If we split it up into a 2D grid (where at its extreme every pixel is its own cell), the neighboring (common) sides of each two cell can be represented by edges of a graph where the nodes such an edge connects are the cells themselves.

If we can find a route across these node edges (grid cells) satisfying our original constraints, we would just draw the elbow arrow itself!

Breadth-First Search

One simple graph search algorithm which finds the guaranteed shortest path in a graph is the humble Breadth-First Search (BFS), which is where we will start our exploration. In essence, BFS tries to visit all the directly connected unvisited nodes from already visited nodes in every iteration (with the start cell being the only visited node at the beginning), until the cell containing the end point is visited. While we do this exploration, we keep a record of which adjacent node we come from for every node as we visit them, forming a contiguous linked list back toward the start node. Then when we reach the end point cell (we can do an early exit, it will be optimal), we can backtrack through the linked list of edges all the way to the start. This will give us the shortest path, but it will not look like an elbow arrow and is definitely not visually pleasing. It is however a start we can build on!

NOTE: If you're interested in diving deeper into BFS, DFS, and how A* works, I recommend this article, which dives deeper into these algorithms and offers interactive visualizations. This article will only cover the key insights building toward the final elbow arrow implementation.

Dijkstra's Algorithm

BFS creates the shortest path to our end cell, it also avoids obstacles, but it doesn't look like an elbow arrow path. To have the right arrow shape (i.e. orthogonal bends), we need to find an incentive for our algorithm to take this desired path. This is where Dijkstra's algorithm comes into play. This algorithm operates on weighted graph edges, using these weights as cost to visit a certain neighbor. To illustrate what this means to our 2D canvas grid, imagine that the canvas has a 3rd depth dimension. The cells along all the possible correct elbow arrow routes are flat, while everywhere else there is a steep height difference, creating a "wall". Our "maze generator" can then take into account all remaining design goals and only create these valleys, which satisfy these requirements. Of course this "maze generator" cannot pre-compute the "terrain" because the grid (or graph) is infinite (Excalidraw has an infinite whiteboard canvas), so we need it to tell us at any cell which neighbors are cheap to visit and which are (preferably prohibitively) expensive.

Distance functions

The answer to our needs is a well chosen distance function of course! This way the edge weights should naturally decrease toward the end cell creating a downward "slope" on our terrain (a negative gradient), while hopefully make incorrect path choices expensive. When we talk distance we often refer to the [Euclidean distance]which is just the length of line segment connecting two endpoints, but there are some clever distance definitions which can help us out in this special maze generation.

Our desired arrow route happens to be a Taxicab or Manhattan geometry and therefore we can use the Manhattan distance calculation to tell at every cell which neighboring cell takes us closer to our goal with it and get (some of) the right shape(s). This is calculated for two cells by first having the familiar Cartesian coordinates ssigned to our 2D grid ([x = 12, y = -5] etc) and then adding together the absolute differences of their coordinates along each dimension. For example, if you have one point at [5, 12] and the other point at [10, -3] their Manhattan distance is |5 - 10| + |12 - (-3)| = 5 + 15 = 20. On the illustration below the green line is the Euclidean distance and the red, blue and yellow are equal Manhattan length paths.

Additional heuristics

Querying the Manhattan distance at every cell we want to visit in our Dijkstra Algorithm give us a metric we can use to generate the "maze" for our search algorithm, but it offers us multiple equally weighted paths and we need to choose the one with the shortest amount of orthogonal bends. So we add an additional term to our "maze generator" to not just consider the Manhattan distance of a neighboring cell and the end cell, but also increase the cost of neighbors if it would be a bend in the path, i.e. our search metric is: Manhattan distance + Bend count. This weighing function paired with Dijkstra's Algorithm now generates correct, visually pleasing elbow arrows if there are no obstacles to avoid.

Exclusion Zones

In order to support shape avoidance we need to support the deactivation of some cells. These should behave like infinitely high walls in our maze, so the graph search algorithm never visits them. This is easily achieved by adding a flag to every cell and mapping shapes to these cells and disabling those cells the shapes cover. However combined with our modified distance calculation it starts to take sub-optimal paths around shapes. The reason is that we can't see the entire "map" (i.e. the grid), it's like a "fog of war" and we uncover it at every iteration of the search algorithm. Obstacles we should avoid well in advance might not be "seen" until it's too late.

Of course introducing a backtracking process is one practical way to address this, but that can be computationally unfeasible. To reduce the unnecessary exploration steps and have a way to incorporate our heuristics, the A* algorithm seemed like an optimal choice. The A* algorithm is similar to Dijkstra's Algorithm, it considers the weight of graph edges, but prioritizes exploring those neighboring nodes (or cells), which offer the best chance to take us closer to the end node (cell) and not waste precious computational cycles. It also promises a one-pass solution, which is also memory efficient.

What is A*?

The key insight of A* is that it balances two factors for every cell (node):

g(n): The actual cost to reach a node from the start. This will be our bend count and some additional heuristics later down the road
h(n): The estimated cost to reach the goal from that node (the Manhattan distance + grid exclusion + even more heuristic functions)
f(n) = g(n) + h(n): The total estimated cost of the path through that node

The algorithm maintains two sets of nodes:

Open set: Nodes to be evaluated
Closed set: Nodes already evaluated

The process:

Add the start node to the open set
Loop until the open set is empty:

Select the node with the lowest f(n) score
If it's the goal, reconstruct the path and return
Move it to the closed set
For each neighbor:
- Calculate tentative g score
- If the neighbor is in the closed set and the new g score is worse, skip it
- If the neighbor isn't in the open set or the new g score is better:
  - Update the neighbor's scores
  - Set the current node as the neighbor's parent
  - Add the neighbor to the open set

If the open set becomes empty without finding the goal, no path exists

By always exploring the node with the lowest f(n) value, A* efficiently finds optimal paths without exhaustively searching every possibility, which exactly what we want. At this stage the implementation mostly worked as expected, but edge cases kept popping up where a human would expect a different routing choice. The other problem was performance.

Performance Optimizations

While the behavior was close, the performance was really starting to cause problems, especially when multiple elbow arrow paths had to be calculated for every frame. Targeting at least 120Hz smooth rendering with ~50 elbow arrows re-routing every frame was a lofty, but achievable goal.

Binary Heap Optimization

The low hanging fruit was obviously the open set of nodes (cells). At every iteration a linear lookup across open nodes is not ideal. The obvious cure is a binary heap data structure with its O(log n) complexity.

Non-Uniform Grid

Operating on a pixel grid (or one node per pixel when looking at it as a graph) makes a significant amount of unnecessary A* iterations (99% and up, depending on conditions), which is a huge waste. Even having cells with just a few pixels is an unimaginable waste (and also wouldn't be pixel perfect).

The solution to this problem is to draw a new grid, which only has nodes on a grid where a potential bend could be. Turns out this is easier than one would think, since aesthetically pleasing elbow arrows always break at shape corners, start and end point headings, and halfway between shapes to be avoided - with optional padding around shapes accounted for.

Since the algorithm operates on graph nodes, nothing forces us to make this a uniformly-sized grid (i.e. for the cells to be exactly the same size). The only thing that matters to A* and the Manhattan distance calculation is neighboring cells and contiguous Cartesian coordinates. Lucky us!

Adapting A* with Manhattan distances for Aesthetic and Performant Elbow Arrows

Aesthetic Heuristics

While the basic A* implementation produced better results than the BFS approach, as mentioned previously, there were some cases beyond the excessive bend count that generated unnatural routes. With carefully constructing additional heuristics, we were able to address these, albeit changes to the A* metric unilaterally affect the behavior in all edge cases, so testing and fine-tuning happened manually to arrive at the final solution.

1. Backward Visit Prevention

Arrow segments are prohibited from moving "backwards," overlapping with previous segments when there is no route other than backwards. This not just prevents spike-like paths (directly reversed segments), but almost completely avoids routes where a U-like arrow configuration would be required to avoid a shape.

This is achieved by tracking the direction of visits and looking back one step and forward one step to recognize the problematic configuration. Together with the very specific grid selection, this prevents the edge cases where this issue would trigger.

NOTE: This only works because there can be at most 2 closed axis-aligned bounding boxes (the shapes) to avoid. With more obstacles in between would certainly re-surface this issue.

2. Segment Length Consideration

Longer (Euclidean distance-wise) straight segments are preferred over multiple short segments, even though previously the Manhattan distance was selected as our main metric driving the A* pathfinding. This is because - again - in some edge cases the non-uniform grid would assume that what it generated was the shortest path, but when projected onto the pixel grid it clearly created short step patterns where it shouldn't. It was especially prevalent with connected shapes being distant from each other.

3. Shape Side Awareness

When choosing between routing left or right around an obstacle, the algorithm considers:

The length of the obstacle's sides
The relative position of start and end points heading-wise (see heading in part 1 of this series)
The parallel or orthogonal relation of the arrow and the shape's bounding box side

4. Short Arrow Handling

Special logic for when the start and end points are very, very close, which prevents excessive meandering and loops. In one case where connected shapes almost overlap and the start and end points are very close, there is a hard-coded simplified direct route because the expected route would never emerge from the algorithm.

5. Overlap Management

The implementation also explicitly detects when shapes cover the start and/or end points. When connected shapes or points overlap, it selectively disables avoidance for one shape or both so there is a valid route possible, even if the exclusion zones would prevent it.

Conclusion

What started as a simple feature request - "add elbow arrows" - evolved into a sophisticated pathfinding challenge. By combining classical algorithms (A*), domain-specific optimizations (non-uniform grids, only two shapes to avoid etc.), and carefully tuned heuristics (aesthetic weights), Excalidraw's elbow arrows speed up diagramming significantly and avoid diagrams previously hand-drawn and hand-managed.

It even made possible some other powerful features like keyboard shortcut flowchart creation which further empower Excalidraw users with serious diagramming needs.

Come join me for the 3rd and final part of this series on elbow arrows, where I walk you through how controlling and fixing arrow segments makes difficult-to-predict arrow routes possible for power users!

Building Elbow Arrows in Excalidraw (Part 1)

Márk Tolmács — Thu, 09 Oct 2025 09:24:29 +0000

As you may know, Excalidraw is an online whiteboarding application that stands out from the crowd with its distinctive hand-drawn, sketchy aesthetic. Despite this (or likely for this very reason) it is loved and embraced by professionals in various verticals including IT, data analysis, engineering, sciences and much more. Their work often includes creating diagrams conveying flows of information or processes, where clarity is paramount. One of the tools they use to indicate connection between concepts or states is arrows, but straight arrows on a busy board can get clunky fast. Therefore a new type of diagramming arrow was needed.

The Case for Elbow Arrows

Enter elbow (or orthogonal) arrows. These arrows follow 90-degree angles, creating clean, professional-looking diagrams that are easy to follow and aesthetically pleasing. Excalidraw users with heavy diagramming workflows already emulated this type of arrow by painstakingly adding points to simple arrows and dragging them into this 90-degree configuration. Therefore it was clear that implementing an arrow type, which supports this arrow routing would bring instant value.

We also quickly realized that it would only be accepted if it "guesses" correctly how a human would route the arrow. This turned out to be the biggest challenge of all. If the arrows look "weird" nobody would use them. So we had to get it right, no matter what "right" means in this context.

Design Goals

We knew from previous experience that we'll definitely need to add additional constraints for passing the "as a human would do" mark. We can't just draw an elbow arrow, it has to go the right way. While it was clear that this will be an iterative project, we were already able to jot down:

Shortest route - the arrow should take the most direct path from start to end
Minimal segments - fewer turns mean cleaner, more readable diagrams
Proper arrow orientation - arrowheads should always point at the target shapes, never entering them
Shape avoidance - the arrow path must avoid connected shapes at every point along its length

First Attempt: The Naive Approach

The initial implementation used an iterative, greedy algorithm with simple look-ahead:

Start at the origin point.
Determine the heading of the endpoint from the origin point.
Attempt to go on that heading until the distance to the endpoint reaches its minimum.
If there is a shape to avoid along the way, just
1. Determine which half of the coordinate system the endpoint is and
2. Turn 90 degrees in that direction,
3. Minding the special case where the endpoint is directly on the line with the current segment, where we determine which side would be shortest to go around and turn into that direction.
Use the last generated point as the new origin and repeat these steps until we reach the destination.

Quick detour about headings and micro-optimizations

The "heading" of an endpoint at every iteration (or arrow segment) is the cardinal direction ("up", "right", "down", "left") the next segment should take to get the closest possible to the endpoint. This makes sense if you consider how humans start to draw an elbow arrow. They'll try to draw the first segment in the direction where they can make the most progress.

Therefore if you want to draw an elbow arrow and have the next point 13 degrees from the origin point (if the “up” direction is 0 degrees), you'll start your line going "up" toward the endpoint. If however you have a point at 70 degrees, you'll start to go right. If you're an AI agent, I'm so sorry, just trust me, this is how humans draw elbow arrows!

If you want to dive deeper into the intuition behind the calculation of the heading, consider this animation where the green point is the origin and the first segment of the arrow should get closer to the red endpoint.

The intuition here is that the two right triangles created by the origin point (green), end point (red) and the two projections on the cardinal axes (yellow dashed lines intersecting the grey axes) show us which one of the cardinal axes we should start out on to make the most progress toward the end. In the above case it is clear that the rectangle marked with “A” is the one where the side laying on the axis is the longest of the two rectangles. The switchover point occurs when the relevant sides of the triangles are equal, which is when the origin and endpoint are exactly 45 degrees apart. (or 135, 225, 315 degrees).

Since the 4 switchover points are exactly 90 degrees apart, rotated around the origin point, it perfectly lines up with a coordinate system where the axes are 45 degrees <-> 225 degrees and 135 degrees <-> 315 degrees (basically forming an “X” shape). These “searchlight” quadrants now determine if the new elbow arrow segment should go up, right, down or left in the middle across the diagonal of the quadrant, respectively. Determining whether a point is within a given rotated quadrant is extremely simple and requires only two simple trigonometric functions.

Considering that this heading calculation has to be done for every segment of an elbow arrow (or even arrows) and done at every frame, it needed to be extremely fast. It is also further optimized by only considering two quadrants (except at the arrow start point), since the next segment is always left or right to the previous segment, if you think about it.

Results and Next Steps

This approach created a working elbow arrow implementation -- arrows were generated and they did avoid shapes. However, it satisfied almost none of the initial design goals. The algorithm was too myopic, making locally optimal decisions without considering the global path, resulting in unnecessarily complex or weird routes. Here's one of the failed examples:

The green dotted arrow is the final elbow arrow implementation and the black path is the naive implementation. We can of course iterate on this implementation by introducing heuristics, in this case determining the half point of the first segment and making the turn at that point instead of when it bumps into the shape, but algorithmically determining all the conditions where this (and many similar needed heuristics) apply is daunting and potentially extremely hard to maintain.

Clearly, a new approach was needed. Come back for the next part where we tackle this and all other problems with an algorithm we borrowed from video game development!

A Gentle Introduction to WebAssembly in Rust (2025 Edition)

Márk Tolmács — Tue, 14 Jan 2025 19:48:34 +0000

Updated: 2025-01-17 Formatting fixes, fix web-sys features by adding 'console'
Updated: 2025-01-17 Video added

Note: If you rather watch a video, a pair-programming session can be found below walking through this article.

Overview

It’s clear WebAssembly is one of the more popular up-and-coming technologies out there. Its promise, a universal executable format, is not new. In fact it dates back to 1995 (almost thirty years ago!) with Java. Arguably, Java was successful in some areas, many enterprise software is built on Java after all, it tried for a brief time (Java Web Start) and eventually failed to ride the stellar rise of the world wide web. Microsoft .NET is a younger contender, but it arguably suffering from the same adoption challenge as Java. While it can run on most systems now, the web is still not one of them.

Enter WebAssembly (or WASM for short), supported by a wide consortium of players, developed in the open and as an open standard, with the WEB as its primary platform. While it’s too early to tell if WebAssembly will be the winner we’ve been waiting for, its adoption is wide enough, the core technology is stable enough that it’s worth considering it for even professional cases. If in doubt, just consider that Figma, the interface design software, is built on C++ and WebAssembly.

Why is a portable, widely supported executable format is such a big deal, you ask? One of the main reasons is that there are a LOT of software already written and most of them are complex systems, not easily ported to other languages and tooling. 99% of the time these software is written in C or C++. WebAssembly offers direct compilation from C, C++ and many more languages an environment (including Rust!) without major hiccups. And that is a previously unseen capital Bid Deal! Besides making software porting almost trivial it’s also a nice benefit that it can often run compute intensive tasks faster than JavaScript.

So in this guide we’ll walk through setting up the tooling and development environment for building and using WebAssembly in Rust, embedding it in a TypeScript project, review how communication between TypeScript and Rust can happen, then finally how you can debug your WebAssembly directly in the browser and/or your favorite IDE. I will use Visual Studio Code as the IDE and Chrome as the browser, but apart from some debugging options, you can reproduce these in your tool of choice.

Note: This guide heavily relies on the excellent Rust WASM Book, which contain a lot more examples and details than this article. I recommend checking it out after finishing this one.

What exactly is WebAssembly?

As mentioned previously, WebAssembly is an open standard of a binary 32 bit instruction set architecture (ISA) for a stack-based, sandboxed virtual machine. That’s a heavy load of terminus technicus, but it’s an apt summary.

In plain English, it means that,

Unlike JavaScript, its final form is binary, not text, similar to how programs on your machine are in binary format.
It is a virtual machine by virtue of not running directly on your hardware as its binary code is translated on-the-fly when you run it, offering the portability you’d expect from a web technology.
Sandboxed, so any interaction with the outside world is carefully scrutinized and approved by the end user, which offers safety guarantees for users that when they load a WebAssembly module on a web page, it cannot access their data or modify their system, unless explicit permission is given.
It’s 32 bit, meaning that we can allocate a maximum of 4Gb of RAM for our WebAssembly application (until WASM64 comes around).
Stack-based is… you know what?! Let this be a concern for compiler developers and let’s get to coding!

Setting Up Tooling

The reference implementations and the most mature WebAssembly development pipeline called Bynarien is still built around C/C++, mainly because the amount of useful code people want to run in the browser was built with C/C++. The Rust community is building it’s own WebAssembly pipeline, however it’s in a state of Tier 2 without Host Tooling at the beginning of 2025. This means that while it is easily and safely used by developers even for production purposes, it lacks some native tooling. This is where we will rely on the Bynarien toolbox to patch in the holes where the Rust WASM pipeline is lacking.

Let’s install the required tools and set up the project:

Install yarn (or npm, or pnpm, if you don’t have it already)

   > corepack enable    # I'll use corepack because I have node@20

Start a new TypeScript project called ‘wasm-on-web’ with Vite (or your framework of choice, if any)

   > yarn create vite wasm-on-web --template vanilla-ts

Commit the current state to Git because we will overwrite some files and you’ll need the old ones

   > git init   # If you haven't initialized the git repo yet
   > git commit -m "Initial setup"

Install Rustup to manage your Rust installation and toolchains

   > curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Set the Rust channel to stable

   > rustup default stable

Download the compilation toolchain for WASM

   > rustup target add wasm32-unknown-unknown

Install some tools we’ll use during our exercise

   > cargo install wasm-tools
   > cargo install wasm-opt
   > cargo install wasm-pack

Install the Bynarien toolkit for our investigations. I use brew, but on Windows you might need to build it yourself or use a package manager like Scoop and use the pre-built package from extras.

   > brew install wabt

Install cargo-generate to quickly scaffold our Rust project over the Vite project we created in step 2

   > cargo binstall cargo-generate   # Install pre-built binary

Note: cargo-generate needs libssl-dev (openssl) installed if you use cargo install cargo-generate

Overlay the Rust project of our TypeScript / Vite project

```bash
> cd wasm-on-web
> yarn install
> cargo generate              \
        --init                \
        --name wasm-on-web    \
        --overwrite           \
        --git https://github.com/rustwasm/wasm-pack-template
```

> Note: `cargo-generate` needs to overwrite some files, because it conflicts with Vite, but the only thing you need to merge is `.gitignore`. You’ll need both the original lines and the newly added ones.

Test if everything works so far
```
> cargo test
> yarn dev  # Should open a web browser
```
With Ctrl + C you can exit the Vite server. You can also commit it into Git now.

Sidenote: Publish your Rust WASM package on npmjs.com

If your WASM code is self contained in Rust, you can build it in production mode and publish it on npmjs.com right now. The wasm-pack tool creates all the TypeScript types, package.json skeleton and anything else needed for a complete package. It is recommended that you review and update your package.json file prior to publishing.

> wasm-pack build
> yarn publish

Build and Integrate the WebAssembly Module

We need to build the WASM module so we can import it in the TypeScript project

   > wasm-pack build --dev

Add the WASM package to our TypeScript project

   > yarn add link:./pkg

Note: It is important to add our WASM package as ‘link’, otherwise when we rebuild the WASM module Vite will not pick up the new version!

Add the Vite plugins required to interoperate with WASM

   > yarn add -D \
       vite-plugin-wasm \
       vite-plugin-top-level-await \
       vite-plugin-wasm-pack-watcher

Configure the WASM loader in Vite by creating vite.config.dev.ts and adding the following contents:

   import { defineConfig } from "vite";
   import wasm from "vite-plugin-wasm";
   import topLevelAwait from "vite-plugin-top-level-await";
   import wasmPackWatchPlugin from "vite-plugin-wasm-pack-watcher";

   export default defineConfig({
     build: {
       watch: {
         include: ["src/**/*.ts", "src/**/*.rs"],
       },
     },
     plugins: [wasmPackWatchPlugin(), wasm(), topLevelAwait()],
   });

Create the production Vite configuration file vite.config.ts and add the following contents:

   import { defineConfig } from "vite";
   import wasm from "vite-plugin-wasm";
   import topLevelAwait from "vite-plugin-top-level-await";

   export default defineConfig({
     plugins: [wasm(), topLevelAwait()],
   });

Note: We can’t use the same config file because of the watch configuration, it would hang the vite build command when we build for production. 6. Add the npm-run-all package as a dev dependency in preparation for the next step below:

Add the npm-run-all package to our TypeScript project to help with running the project

     > yarn add -D npm-run-all

Note: This is a platform-independent way to run npm scripts one after the other with the run-s shortcut, which makes it possible for the Windows folks to follow this tutorial without issues. Even if you don’t use Windows it’s polite to have a solution in place which works for all.

Modify “scripts” section in package.json to call wasm-pack before starting Vite for all configurations, so a fresh WASM build is always ready for us at the start dev start and the final WASM module is build in release mode before vite production build happens:

   {
     ...
     "scripts": {
       "build": "run-s wasm-pack:release tsc vite:build",
       "dev": "run-s wasm-pack:dev vite:dev",
       "tsc": "tsc",
       "vite:build": "vite build",
       "vite:dev": "vite -c vite.config.dev.ts",
       "vite:preview": "vite preview",
       "wasm-pack:dev": "wasm-pack build --dev",
       "wasm-pack:release": "wasm-pack build"
     },
     ...
   }

Start the Vite dev mode and continue with writing our Rust WASM code

   > yarn dev

Exporting and Importing in Rust

Opening up src/lib.rs we can see that we have a greet() function already exported and ready for us to be called. We know it’s exported because it has the [#wasm_bindgen] macro applied to it from the wasm-bindgen package.

#[wasm_bindgen]
pub fn greet() {
    alert("Hello, wasm-on-web!");
}

Note: You can in fact add the #[wasm_bindgen] macro to enums, structs and impls, not just stand-alone fns!

There’s another trick in this file above the greet() function, which you’ll use when you want to call JavaScript functions:

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

This specifices an extern block which contain external (JS) functions we want to call from our Rust WASM module. These can be called with the C calling convention, not the Rust calling convention, hence extern “C”. These should be wired up between JS and Rust too, so you need to add the #[wasm_bindgen] macro here as well. Not unsurprisingly, this is unsafe and since the Rust compiler won’t be able to verify whether the external function exists, it’s calling signature (parameters) are properly typed, present and ordered the right way. Specifying these incorrectly very likely will crash your program.

Importing From and Exporting To WASM in TypeScript

Now it’s time to open src/main.ts and import our new Rust WASM module at the top of the file.

import { greet } from "wasm-on-web";

Then on the bottom, just simply call the greet() method we just imported.

// Call the greet function from WASM with the
greet();

All the translation, loading the WASM module and configuration is being taken care of by wasm-bindgen, the Rust package our template installed. Even TypeScript type definitions are generated for us.

If everything went well and yarn dev is running, the browser is open, we’ll see the alert right from the Rust code.

If you want to call your JavaScript functions in Rust, you already saw how it is done with the alert() JS function. One additional step is required, namely that you have to add your function to the global window object.

// Just to resolve TypeScript errors
declare global {
  interface Window {
    jsFunction: () => void;
  }
}

window["jsFunction"] = () => {
  alert("Hello from JS!");
};

Then you’re ready to declare and call it in Rust.

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
extern "C" {
    fn alert(s: &str);
    fn jsFunction();
}

#[wasm_bindgen]
pub fn greet() {
    jsFunction();
}

Passing Primitive Parameters Back and Forth

A function call seldom worth much without passing data to it in the form of parameters. wasm-bindgen takes care of this too in simple cases and almost completely in heap allocated types. For example, if you want to pass a custom name to greet to our greet function implemented in Rust, you could do this:

#[wasm_bindgen]
pub fn greet(name: &str) {
    alert(format!("Hello {}!", name).as_str());
}

On the TypeScript side, just simply pass the parameter and we’re ready to go:

greet("this is TS");

It should show the alert dialog with our new parameter:

For the other direction, we’re already seen with the native alert(…) function, just pass the string slice to the JS function and wasm-bindgen takes care of it.

So what happens when you need to use complex types, maybe heap allocated types as parameters? That’s what we’re dealing with next.

Using existing JavaScript APIs and Functions

I don’t know about you but I’ve had just about enough of the alert dialog and would like to use console.log(…) and similar native JS APIs. We could wire them up manually, figure out the complex parameter definition, but there is an easier way: The web_sys package. Let’s install it! Add this to your Cargo.toml file:

[dependencies.web-sys]
version = "0.3"
features = [
  "Window", "console"
]

We can get rid of our manually implemented alert() mapping and use the web_sys console.log implementation going forward:

#[wasm_bindgen]
pub fn greet(person: &str) {
    web_sys::console::log_1(&format!("Hello {}!", person).into());
}

Passing Complex Parameters Back and Forth

With complex types we need to consider the fact that what’s a complex type in one language might not be so in the other. A typical example of this is String. String is an owned, complex type in Rust and behaves like a primitive in JavaScript. wasm-bind hides this difference by making a copy in WASM memory of your JS string when you expect a String parameter type in Rust. You can make it mutable, but it will only modify the Rust copy of the String, it will not propagate back to the JS string. In order to have two-way communication, we have to put in some legwork.

If you have a JS class or object which you’d like to receive as a parameter on the Rust side, you’ll have to define the mapping as an extern “C” block. Let’s say we have a JS class defined in TS:

class TSDef {
  constructor(public id: string) {}

  run() {
    console.log(this.id);
  }
}

On the Rust side if we want to access the id property and the run method, we have to map it and use it the following way:

#[wasm_bindgen]
extern "C" {
    pub type TSDef;

    // Uses the JS "get()" method which is
    // provided by the "class" base prototype chain
    #[wasm_bindgen(method, getter)]
    fn id(this: &TSDef) -> String;

    // Uses the JS "set()" method which is
    // provided by the "class" base prototype chain
    // NOTE: "set_<property>" naming is important!
    #[wasm_bindgen(method, setter)]
    fn set_id(this: &TSDef, val: &str);

    #[wasm_bindgen(method)]
    fn run(this: &TSDef);
}

#[wasm_bindgen]
pub fn remote_instance_param(tsdef: &TSDef) {
    // Display the id of the instance
    alert(tsdef.id().as_str());

    // Modify the id on the JS instance
    tsdef.set_id("zyxw");

    // Call a method on the JS instance
    tsdef.run();
}

Now if you call the remote_instance_param() function from TypeScript, you’ll see an alert with the original “abcd” message from JS and a console message with “zywx” from the run() method invoked from Rust reading the modified id value and printing it on the console.

What if we want to expose a Rust type to JS? A similar mapping needs to take place. Let’s have a Person struct which we would like to use in JS:

#[wasm_bindgen]
pub struct Person {
    pub id: u32,
    name: String, // String is not Copy, so we cannot make it public!
}

// Implement a constructor and a getter/setter for the String field
#[wasm_bindgen]
impl Person {
    #[wasm_bindgen(constructor)]
    pub fn new(id: u32, name: String) -> Person {
        Person { id, name }
    }

    // Getter which automatically gets called on the JS side
    #[wasm_bindgen(getter)]
    pub fn name(&self) -> String {
        self.name.clone()
    }

    // Setter which automatically gets called on the JS side
    #[wasm_bindgen(setter)]
    pub fn set_name(&mut self, name: String) {
        self.name = name;
    }
}

In the TS/JS side, we can then simply import it and use it with one big caveat:

import { greet, Person } from "wasm-on-web";

// Create a Person object which is shared between WASM and JS
const person = new Person(2343, "John");

// Automatically call the setter on the Rust side
person.name = "Jane";

// Call the greet function from WASM with the
greet(person);

// Don't forget to free the WASM memory when you're done with the shared object!
person.free();

Because the Person type is a WASM type defined in Rust, we need to take care of the de-allocation ourselves when we no longer need it. Unfortunately there is no Drop mechanic and the memory of JS-allocated Rust native types need to be freed manually!

Debugging WebAssembly

Now that we have seen how we can transfer data between the two sides, we also became aware of how fragile is the whole setup. Having a robust debugging workflow is essential to quickly identify and root out the inevitable issues.

To date the best option to do so is via a Google Chrome extension, C/C++ DevTools Support (DWARF), built by Google’s Engineers. DWARF is one of the debugging information formats for binary code and it’s the type of debug info Rust generates by default, so it’s ideal for our debugging needs. Unfortunately this is Chrome only, so you’ll have to stick with Chrome.

Once you added this extension to your Chrome, restart the browser so it loads the extension proper. Next you’ll need to enable a setting in the DevTools settings panel (see the cog icon on your DevTools panel after you opened it). It’s called “Allow DevTools to load resources, such as source maps, from remote file paths. Disabled by default for security reasons.”

Now the browser is ready, we need to set up the Rust side. First, make sure you have the Rust source code installed, because the stack traces most definitely will go into the Rust standard library and having a nice source view into those files will help us figuring out what’s going on much easier than without it.

> rustup component add rust-src

We also need to modify our Cargo.toml because by default wasm-pack strips out the DWARF debug information. Add this to the end of Cargo.toml:

[package.metadata.wasm-pack.profile.dev.wasm-bindgen]
# Keep the DWARF debug info for debugging in dev mode
dwarf-debug-info = true

Note: You may need to clear your browser cache in order for this to work.

Now if you start your Vite project with vite dev and load it up in Chrome, then check out the DevTools console, you should see something like this:

This is a good sign that the Chrome extension found the debug information and loaded it into the DevTools.

Note: If you can’t see this message and can’t debug your WASM, then check the generated *.wasm files for DWARF debug info. Install wasm-objdump from HomeBrew and see if you can find “.debug_str”, “.debug_line” and similar custom sections in your WASM. If not, then the DWARF debug info is missing, therefore the extension has nothing to work with.

You can also run your project with RUST_LOG=info yarn dev to see if the wasm-pack step runs cargo build with the —keep-debug parameter.

Finally if you run yarn dev —debug you can see what files the browser requests from Vite and if you see it requesting *.dwg file(s), then the browser extension is working properly, your WASM file should be the problem.

If you open up your sources tab in DevTools, you’ll see that there is a file:/// major section previously missing. Opening it you’ll find your project directory, in it you’ll see the Rust source file, lib.rs loaded and available. You can now set breakpoints in it and debug like you would a JS file. You can also see the variable values, which might not be immediately useful, but often enough to figure out what’s going on.

One other benefit this extension brings us is if there is a panic in our code, we will see the stack trace in console with rust file names, line numbers and character positions! Certainly helpful!

Note: If you see an error message on the Sources tab that refers to files cannot be open, specifically when it starts with file:///rustc/<hash> then you need to set up a mapping to your rust sources.

In case you need to map some directories from the WASM debug informatin, maybe because you built it on a remote machine and your files are in a different folder, there is a way to do it in the Chrome extension settings. Open it up and add the directory mapping from the /rustc/<hash>/ to the absolute path of your Rust sources.

My mapping was /rustc/90b35a6239c3d8bdabc530a6a0816f7ff89a0aaf => /home/mtolmacs/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/src/rust. Yours might be different.

In case you need to figure out the Rust toolchain directory on your system, you can use the following command:

> rustc --print sysroot

Sidenote: WebAssembly on the server-side

While eminently useful for bringing large-scale applications like Figma to the web, it’s gaining popularity on the server-side as well. Highly distributed apps use it as a platform agnostic edge runtime and the Web3 community found use for it as an open platform for smart contract runtimes on the blockchain. One other interesting use-case is platform-independent plugins for tools like the SWC JavaScript / TypeScript transpiler created by Vercel.

The solution all these projects use is called WASI, the WebAssembly System Interface, which is a true standard library to access all system resources, just like you would with Rust or C. However WASI is quite young and still not a stable standard. NodeJS just started to support running WebAssembly with WASI in node@23, so it is quite experimental yet. Other runtimes like wasmtime can run the WASI Preview 1 and is reasonably stable.

So as a final act, let’s download and build a sample WASM app using WASI to open stdio handlers and uses SWC to transpile the input, the output the result.

> git clone https://github.com/zebp/wasi-example-swc

Time to add the Rust WASI runtime.

> rustup target add wasm32-wasip1

Time to compile it to WASM WASI.

> cargo build --target wasm32-wasip1

Check if NodeJS is at least 23.

> node -v

Finally create the loader JavaScript which loads the WASM (change the preopens mapping to avoid any errors)

"use strict";
const { readFile } = require("node:fs/promises");
const { WASI } = require("node:wasi");
const { argv, env } = require("node:process");
const { join } = require("node:path");

const wasi = new WASI({
  version: "preview1",
  args: argv,
  env,
  preopens: {
    "/": "/Users/mtolmacs/Projects/wasi-example-swc/",
  },
});

(async () => {
  const wasm = await WebAssembly.compile(
    await readFile(
      join(__dirname, "../target/wasm32-wasip1/debug/swc-wasi.wasm")
    )
  );
  const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject());

  wasi.start(instance);
})();

Time to run it:

src > cat examples/async-generator.js | node loader.js

If you want to use wasmtime, just install it and run the WASI WASM directly!

> brew install wasmtime

> cat examples/async-generator.js | wasmtime target/wasm32-wasip1/debug/swc-wasi.wasm

Continue learning about Rust and WebAssembly

If you’d like to continue learning about Rust and WebAssembly, I highly recommend reading through the Rust WebAssembly Book and then follow up with the The wasm-bindgen Guide for the practical training material.