Compatibility With Node.js
Bun’s goal may be to serve as a “drop-in replacement for Node.js,” but that compatibility is still a work in progress. Bun uses the same module resolution algorithm as Node.js, with many built-in and global modules fully supported. However, others are only partially implemented, and a number aren’t implemented at all. Prominent Node.js contributor Matteo Collima noted this in a generally positive article about Bun, writing “In my experience, it’s not a drop-in replacement, and many inner details differ. This results in many random issues over my repos asking for fixes for Bun incompatibilities while people try it out…Ultimately, Bun does not implement all Node.js APIs. It’s not a clean drop-in replacement for Node.js (despite their claims).”
The Bun team regularly updates the compatibility page as support is improved. Make sure to read up on the latest details there before deciding if Bun will meet the needs of a project currently using Node.js.
How Does Bun Stack Up?
None of that actually answers the question: Is Bun faster? The answer appears to be “Yes!” at least in basic “hello world” scenarios. The test results at that link clock Bun’s native server at twice the speed of Node.js, and 1.5 times the speed of Deno.
- Developer experience: One of the ideas behind Bun was to combine a package manager, bundler, and test runner into a cohesive toolkit for building apps, eliminating the many layers of tooling used by Node.js. It’s an attractive notion, but the execution is not without its critics.
In Bun Hype: How We Learned Nothing From Yarn, Jared Wilcurt argues “Bun is just an abstraction layer on top of the tools we already have. Meaning it will always be behind the curve and can introduce additional bugs at that layer. Not ideal for such mission critical systems like installing dependencies, testing code, and building the code to be sent to production.”
- Transpilation: Most runtimes require a separate build step to transpile source code before executing it. Bun handles transpilation source code automatically at runtime. We’ll look at this a little deeper in the next section.
How Bun Handles Transpilation
Bun transpiles source code automatically at runtime, eliminating the need for a separate build process. For example, TypeScript and JSX files can be executed directly:
// index.tsx const element = <h1>Hello World!</h1> console.log(element)
No Intermediate Output
To avoid re-transpiling unchanged modules, Bun intelligently caches transpiled module outputs. The cache is invalidated when source files change.
There are a few different ways to install Bun, including with
cURLon macOS, Linux, and WSL:
curl -fsSL https://bun.sh/install | bash
Bun’s installation page also includes instructions for installing the runtime through npm, Docker, Homebrew, and Proto.
Alternatively, you can download the binaries for Bun directly from the the releases page. Make sure to select the appropriate file for your operating system and CPU architecture.
bun command is the starting point, providing subcommands for running code, bundling projects, executing tests, and more:
bun build: Bundle for production.
bun test: Run tests with Jest-style API.
bun install: Install dependencies.
bun init: Scaffolds a new project through an interactive tool.
Bun uses the same
package.json workflow as Node.js to install dependencies, with the command bun install used to install all dependencies on a project. To install a particular package, you’d use
bun add, followed by the name of the package. Packages are stored in a global cache, with subdirectory names indicating both the package name and version. This allows you to cache multiple versions of the same package. Imported packages are installed on the fly during execution.
Getting Started With Bun
Bun has a lengthy list of code examples and guides to get you started. We suggest following the Quickstart to create a simple HTTP server and get a feel for how Bun works. From there, you can move on to importing JSON and TOML files, run tests in watch mode, and use React and JSX.
It’s natural to see a lot of hype surrounding any shiny new tool, and that’s the position Bun is in right now. Time will tell if Bun lives up to the hype, and truly becomes the drop-in replacement for Node.js it’s been touted to be.
Have you used Bun, either on a project or for educational purposes? Do you think it will be around for the long haul, or more of a flash in the pan? Let us know in the comments.