The definitive guide to using Bun

Bun recently hit its 1.0 release. If you’re not familiar with it, Bun aims to replace Node.js (the runtime) and a bunch of npm packages for common workflows, very similar to Deno. Built from the ground up, it promises speed and simplicity. Cool! After all, who doesn’t want speed and simpicity?

This guide is intended for unassuming folks who notice all the hype around this new promising tool and think, “how exciting! maybe I should try this”.


Getting started?

While 1.0 is simply a number and generally only means API stability, Bun explicitly promises production-readiness and boasts about being a “drop-in replacement” for Node.js. These claims are quite bold indeed. Even Deno, which has been around for a few years now, still doesn’t dare make such bold claims.

And yet, Bun literally doesn’t support Windows! As a long time Windows user, I see this as a big “fuck you”. A self-proclaimed “production-ready” tool has no business not working on Windows. Not everyone can afford to buy a fancy Apple device, and many employers don’t offer a choice.

Let’s say you do use a Mac. What you’ll quickly find is that the other claims are also bogus. When you go try it in your existing projects, things will very likely break in nasty ways.

Matteo Colina, a core contributor to Node.js, wrote about being frustrated by Bun’s compatibility claims after receiving random Bun-related issues in their GitHub repos.

This makes total sense, you can’t just recreate over a decade of hard-work by countless contributors in a few months with a small team; it is physically impossible. So why market yourself as such?

Marketing. That’s all it is. A marketing stunt.

The techbros giveth

You needn’t look too deep to find that Oven, the company formed around Bun, is backed by $7 million in VC funding. Their goal is to sell you serverless hosting that utilizes Bun. Suddenly it starts to make sense why they might want to push for a “stable” release on an impossibly tight timeframe.

“But no one is forced to use Oven for hosting”, you might say. That’s true, Vercel already supports Bun install, right? (Read that again, slowly and carefully.)

The techbros taketh

I will not ask you to imagine what happens when Oven is unable to make a profit. I will not ask you to look into the founder being a proud Thiel Fellow and why that’s problematic.

What I do ask is for you to evaluate this now-deleted tweet from a year ago:

Tweet from @oven_sh posted on August 23, 2022: Oven is going to be a grind, especially in the first nine months or so. If work-life balance to you means a lot of time spent not working, it's probably not a good fit right now.

The name “Oven” is quite fitting really, as anybody who enters this company will inevitably end up burnt out. I could maybe understand the “grind” mindset if you do not care about your own health; but to ask the same of your employees and loudly announce that you are going to be an unapologetically shitty employer is a totally different thing.

Lots of people called it out when it was tweeted. But it seems like almost everyone has now forgotten all about it, or worse, has decided to overlook it.

“At least they were being upfro—” Stop. Would you be friends with your college roommate who is “at least being upfront” about being a fascist homophobe?

Does it matter?

Tech is inherently political and I think there is value in recognizing that, even if we’re unable (or unwilling) to change the tools we work with.

Maybe you’re someone who does not care about any of this. Maybe you just like the theoretical idea of shaving off a few milliseconds. You’re probably screaming “just tell me how to use it ffs”. I ask you again to stop and reflect. Once you cut through all the hype, what is it you’re really hoping to get out of it? At most an experiment maybe? Be honest about your hopes (and later about your findings).

With all that said, I do think it is good for Node.js to have competition. Node comes a lot of baggage, and without competition there would be no strong incentive for Node to improve. Deno (which I’m also not fond of, for different reasons) is probably what pushed Node to eventually embrace so many Web APIs like fetch. But that’s a whole different conversation for another day.