<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>The Books I Have Read Since April 2025</h1>
<p>It has been a slow couple of months for my reading habit.
Although, now that I've said that out loud, I realize I say that every time.
I never quite read enough books by the time I feel ready to write one of these reading reviews.</p>
<p>In the interest of brevity, let's jump straight in.</p>
<h2><em>How to Stop Time</em> by Matt Haig</h2>
<p>After reading <em>The Midnight Library</em> in <a href="/the_books_i_read_in_january_2025">January</a>, I was thoroughly impressed by Haig's work.
I wanted more, but wasn't sure what to read next.
So, the next time I saw a book with an interesting title which happened to be his, I picked it up.</p>
<p>If <em>The Midnight Library</em> was a literary therapy session, <em>How to Stop Time</em> is a history lesson.
It follows a man who ages at one-tenth the rate of a normal human.
Despite being given the gift of extra life, he regularly falls into spats of depression when his loved ones die before him.</p>
<p>While Haig's writing continues to be sentimental and appreciative of the small things in life (a trait few seem to possess these days), I ultimately found the book predictable and unengaging.
It was a good book, and I felt satisfied having read it, I had put it down for a few days at a time more than once to do so.
If you're going to read just one of Haig's books, it shouldn't be this one.</p>
<h2><em>Everything is Tuberculosis</em> by John Green</h2>
<p>I've been a fan of John Green's work since I was kid.
I remember reading <em>Looking for Alaska</em> as I cruised down the Mississippi River on a school trip.
It was one of the most memorable books (and expeditions) I've had the pleasure of experiencing.</p>
<p>Naturally, I was ecstatic to hear John Green published something new: <em>Everything is Tuberculosis</em>, a book about the facets of our lives (of which there are many) that we can thank TB for.</p>
<p>I liked this book, but I don't think it matches the reflective attitude about the human experience you find in his other books—but that's a good thing!
<em>Everyhitng is Tuberculosis</em> is not a book you're supposed to relate to, but a book that tells a story about a life most in the western world find completely unfamiliar.
One where each and every day is counted.
One where the price of a medication is the most important number.
One where you might not survive.</p>
<p>The fact that I couldn't relate to the events in <em>Everything is Tuberculosis</em> is the exact reason why I'm glad I read it.</p>
<h2><em>How to Win Friends and Influence People</em> by Dale Carnegie</h2>
<p>I read <em>How to Win Friends and Influence People</em> (a mouthful, I know) not because I needed advice on the subject.
I read it because I believe this book to be a telling window into the minds of the businessmen of the early 20th century.</p>
<p>I've been told that this book is still relevant today; that the advice still works.
I disagree.
The priorities, values, and culture are entirely different today than when this book was written.
I found it fascinating to compare and contrast between my own experience and the author's.</p>

It has been a slow couple of months for my reading habit. Although, now that I've said that out loud, I realize I say that every time.

<p>It has been a slow couple of months for my reading habit. Although, now that I've said that out loud, I realize I say that every time.</p>

The Books I Have Read Since April 2025

<h1>Harper in Firefox Through SpellBolt</h1>
<img src="/images/ford_street.webp" alt="Ford Street, Golden, Colorado">
<p>We designed Harper to be the ultimately portable grammar checker, but we're still working on living up to that promise.
As the Harper Chrome extension becomes more capable day-by-day, it has one critical weakness: it doesn't support Firefox.
Since Chrome has a much larger market share, it isn't a priority at the moment (although we accept contributions).</p>
<p>This is a wonderful example of where the open-source nature of the Harper's core engine really shines.
Someone has taken <a href="https://www.npmjs.com/package/harper.js"><code>harper.js</code></a> and put it into their own extension.
<a href="https://addons.mozilla.org/en-US/firefox/addon/spellbolt/">SpellBolt</a> is a Firefox extension that delivers Harper's fantastic grammar checking straight into your Firefox browser.
My initial testing shows that it's a solid extension.</p>
<p>I am delighted to see people making use of the pluggable architecture Harper has adopted, and I can't wait to see what SpellBolt does next.</p>

SpellBolt is a Firefox extension that delivers Harper's fantastic grammar checking straight into your Firefox browser.

<p>SpellBolt is a Firefox extension that delivers Harper's fantastic grammar checking straight into your Firefox browser.</p>

Harper for Firefox Through Spellbolt

a_harper_record

<h1>A Harper Record</h1>
<p>When we started work on <a href="https://writewithharper.com/docs/harperjs/introduction"><code>harper.js</code></a>, our goal was simple.
We wanted it to take less than 24 hours for a developer to embed high-quality grammar checking in their app.</p>
<p>A friend of mine, <a href="https://lukaswerner.com/">Lukas Werner</a> recently set a record for this.
In just over 15 minutes, he was able to embed Harper into Raycast, a command palate for MacOS.</p>
<p>This is fantastic news.
It's always great to see when your goals are having a real impact on someone's ability.</p>
<p>I hope you take the time to look at <a href="https://github.com/lukasmwerner/harper-raycast">the project on GitHub</a>.</p>
<p>In other news, we have some other small projects using Harper:</p>
<ul>
<li><a href="https://github.com/lockbook/lockbook">Lockbook</a></li>
<li><a href="https://stubby.io/">Stubby CMS</a></li>
</ul>

Elijah Potter

A Harper Record

Other Stuff

Footguns of the Rust Webassembly Target

The Books I Have Read Since April 2025

Harper for Firefox Through Spellbolt