<h1>Footguns of the Rust WebAssembly Target</h1>
<img src="/images/rail.webp" alt="A trail in Golden, Colorado">
<p>WebAssembly—even after several years of standardization—is still a nascent technology.</p>
<p>I've been working with Rust and WebAssembly for nearly four years now.
This post is intended to be a distillate of that experience, formatted for developers who are interested in publishing WebAssembly code to npm.
Specifically, these are the footguns I've personally encountered while working on <a href="https://writewithharper.com/docs/harperjs/introduction"><code>harper.js</code></a>, a WebAssembly-powered package for grammar checking at the edge.
This page should be valuable if you are even speculating on the possibility of using WebAssembly in your codebase.</p>
<hr>
<h2>1. Exposing Only Synchronous Functions</h2>
<p>The Harper package exposes one interface that captures all of its WebAssembly interactions: the <strong>Linter</strong>. This is an object that handles downloading and compiling the Harper WebAssembly module, as well as invoking functions in it. Every function returns a <code>Promise</code>. There are several good reasons for that:</p>
<ul>
<li>WebAssembly modules larger than 4 kilobytes must be instantiated <strong>asynchronously</strong> to avoid blocking the event loop during download or compilation. This is a technical limitation that cannot be avoided with clever logic.</li>
<li>If most functions are asynchronous, you can centralize computation and caching into a single instance of the WebAssembly module, hiding the complexity of instantiation and making caches easier to build.</li>
<li>If your problem domain can be computationally intense, it might be prudent to offload jobs onto a <strong>web worker</strong>, which is easier if every function of your facade is asynchronous.</li>
<li>It will be easier for both you and your users to expose any important function as asynchronous out of the gate.</li>
</ul>
<h2>2. Assume Rust Can Trivially Do IO</h2>
<p>Whatever you do: avoid assuming that Rust libraries (like <code>reqwest</code> or <code>rand</code>) will be able to perform IO without some work on your end. WebAssembly alone is <strong>not capable of IO</strong>, which means any function in that category will require some amount of JavaScript to work properly.</p>
<p>Rather than leaving that up to the Rust toolchain to figure out, save yourself the headache and <strong>inject the necessary JavaScript functions</strong> directly into the WebAssembly module by passing them through <code>wasm_bindgen</code>.</p>
<hr>
<h2>3. Just Inline the WebAssembly Module</h2>
<p><strong>Obsidian plugins</strong>, for example, must be composed of exactly one JavaScript file, which means everything must be inlined. In the interest of keeping the bundle size small, it's much easier for the package developer (of <code>harper.js</code>) to set up inlining than the plugin developer.</p>
<p>On the other side of the spectrum, <strong>Chrome's Manifest V3</strong> disallows WebAssembly from being loaded inline.</p>
<p>If you plan for your package to be consumed by a variety of applications, know that it will also be consumed by a variety of <strong>bundlers</strong>. Both bundlers and applications are pretty inconsistent with their inlining and tree-shaking behavior. To avoid problems, you should provide <strong>two versions</strong> of your package:</p>
<ul>
<li>One where your WebAssembly module is already inlined.</li>
<li>One where it isn't.</li>
</ul>
<h1>Wrapping it Up</h1>
<p>Harper’s problem domain is not your problem domain.
We have to integrate with a variety of unique applications, which means we must keep our system flexible.
That may not be the case for you, which may mean these footguns do not apply.
If you have any questions about any other problems the Harper project might have faced, let me know.</p>

Four years in Rust + WebAssembly taught me these 3 lethal footguns—don’t learn them the hard way.

<p>Four years in Rust + WebAssembly taught me these 3 lethal footguns—don’t learn them the hard way.</p>

Footguns of the Rust Webassembly Target

<h1>Why You Need <code>sccache</code></h1>
<p>As the maintainer of a <a href="https://writewithharper.com">reasonably popular open source project</a> written in Rust, I find myself cloning PRs and swapping between branches dozens of times a day.
In doing so, I often blow away Rust's compilation cache either via <code>git clean -xf .</code> or by changing dependency versions.</p>
<p>Having a build cache that is separate from the project is a huge win for compile times, which is why I use <a href="https://github.com/mozilla/sccache"><code>sccache</code></a>.</p>
<p>For those unaware, <code>sccache</code> is a build tool for C, C++ and Rust projects that stands in front of the compiler.
If a given file's hash is the same across calls to the compiler, <code>sccache</code> reuses the previous result.
This cache is compiler–and project agnostic.
In my case, it sits in <code>$HOME/.scccache</code>, but you can set it up with AWS S3, Redis or a myriad of other options.</p>
<p>If a dependency is cached from a compile in one project, it is available for a build in another.</p>
<p>In short: you need <code>sccache</code> if you are frequently swapping between branches with similar (but not identical) dependencies or expect to frequently delete Rust's disk cache.</p>
<h2>Why You Don't Need <code>sccache</code></h2>
<p>If you are working in a single branch on a project whose dependencies remain somewhat stable, <code>sccache</code> might actually increase your compile time.
Since <code>sccache</code> has to hit the disk (or even the network) regardless of whether it is a cache hit, a little bit of latency is added.
If you expect most compiles to be cache hits or most compiles to be cache misses, <code>sccache</code> is no more useful than the built-in caching <code>cargo</code> provides.</p>
<p>In that case you should not use <code>sccache</code>.</p>
<h2>Wrap-Up</h2>
<p>Regardless of whether you install <code>sccache</code> on your machine, it is a neat little technology.
I would recommend the curious reader take a look for themselves.
You might be inspired.</p>

Why You Need Sccache

How I built a software render engine from scratch, and you can too.

<p>How I built a software render engine from scratch, and you can too.</p>

Building a Software Render Engine from Scratch

the_three_steps_to_an_apology

<h1>The Three Steps to an Apology</h1>
<p>My grandmother is a wonderful woman. She never leaves the house without a least a little bit of purple. Maybe a keychain or a purse. Sometimes, she wouldn't leave the house without a lot of purple, head to toe. She also never forgets a smile and a good attitude.</p>
<p>She's a wise woman. With more than 70 years and five children under her belt, she's seen some stuff. All that experience comes with a lot of advice. The three steps to an apology are some of the best bits of advice she's ever given me.</p>
<h2>Step One: "I am sorry"</h2>
<p>Admit you've done something wrong. Recognize your fault and imagine what would have happened if you had done the right thing.</p>
<h2>Step Two: "It will not happen again"</h2>
<p>If you're actually sorry, you'll want to avoid replicating the same mistake at a later date. Figure out what you need to do to make sure you this is a one-time error.</p>
<h2>Step Three: "What can I do to make it better?"</h2>
<p>Attempt repair. In a fantasy world, you could go back in time and stop yourself from doing whatever it is you did in the first place. But we don't live in a fantasy world, so you have to find a way to make it right, as soon as possible.</p>

Elijah Potter

The Three Steps to an Apology

Step One: "I am sorry"

Step Two: "It will not happen again"

Step Three: "What can I do to make it better?"

Other Stuff

Footguns of the Rust Webassembly Target

Why You Need Sccache

Building a Software Render Engine from Scratch