Bun: a drop-in Node.js runtime that also replaces your package manager, bundler and test runner

The four tools Bun collapses into one binary

The README describes Bun as "an all-in-one toolkit for JavaScript and TypeScript apps" that "ships as a single executable called `bun`". That sentence is the whole product argument. In a conventional Node.js setup you install a runtime, a package manager, a bundler and a test runner, then keep four config files and four upgrade cycles in sync. Bun's command line implements all four: `bun run` executes a script or a file, `bun install` resolves dependencies, `bun test` runs tests, and `Bun.build` bundles. The audience is anyone maintaining a Node.js codebase who is tired of the toolchain rather than of JavaScript itself.

The claim that carries the most weight is "drop-in replacement for Node.js". That is a compatibility promise, not a feature, and it is the one worth checking against your own dependency tree before you make any decision. The README points to a dedicated Node.js compatibility page in the docs, which is the honest place to look for gaps.

The second claim is speed. The README says Bun is "written in Rust and powered by JavaScriptCore under the hood, dramatically reducing startup times and memory usage". Note the wording: the runtime is Rust and JavaScriptCore. The repository's Cargo.toml lists roughly a hundred workspace members, including src/bundler, src/install, src/http, src/sql, src/shell_parser and src/resolver, so the package manager and bundler are Rust crates compiled into the same binary rather than separate processes. That is the mechanism behind the startup numbers, and it is also why the binary is large and platform-specific.

Why JavaScriptCore and Rust change the startup profile

Node.js runs on V8. Bun runs on JavaScriptCore, the engine from WebKit, and the README states this plainly. Engine choice affects startup and memory far more than it affects steady-state throughput, which is why the README frames the benefit as "dramatically reducing startup times and memory usage" rather than as faster execution. For a long-running server that distinction matters less; for a CLI that starts hundreds of times in a CI run, or for a serverless function that boots per request, it matters a lot.

The Rust layer is what makes the all-in-one claim possible. A workspace member like src/install is the package manager's resolution and extraction logic; src/bundler is the bundler; src/shell_parser backs the built-in shell. Because these are libraries inside one process, `bun install` does not shell out to a JavaScript process to read a manifest. The repository also carries a rust-toolchain.toml and a flake.nix, so building Bun from source is a Rust build, not a Node.js build.

One consequence is worth stating plainly: a single binary that does four jobs has a single failure surface. If `bun install` mishandles a corner of the npm registry protocol, you cannot swap in npm for that one command without also changing how the rest of your workflow resolves modules. The README's own framing, "usable in existing Node.js projects with little to no changes", is a claim about typical projects, not a guarantee about yours.

Installing Bun and running a TypeScript file without a build step

The README lists four install paths. The install script is marked recommended:

curl -fsSL https://bun.com/install | bash

On Windows the README gives a PowerShell equivalent, and there are npm and Homebrew routes:

npm install -g bun
brew tap oven-sh/bun
brew install bun

If you would rather not touch the host, the README documents a Docker image:

docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun

The README notes that Linux users should have kernel 5.6 or higher (5.1 is the stated minimum), and that x64 users who hit "illegal instruction" errors should check the CPU requirements linked from the installation page. That is a real constraint, not boilerplate: Bun is compiled against a CPU baseline, and older x64 hardware can fall below it.

The first real use is the one the README leads with. Save a file with TypeScript or JSX in it and run it directly:

bun run index.tsx

The README states that TypeScript and JSX are supported out of the box, so there is no tsc step and no ts-node wrapper. The other commands follow the same shape:

bun test
bun run start
bun install <pkg>
bunx cowsay 'Hello, world!'

`bun test` runs the built-in test runner, `bun run start` executes the start script from package.json, `bun install <pkg>` adds a dependency, and `bunx` executes a package without installing it globally. Upgrades go through the binary itself:

bun upgrade

The README also documents `bun upgrade --canary`, which installs the build produced from every commit to main. Use that only if you are deliberately tracking unreleased behaviour.

Where Bun is the wrong tool

The README does not document a rollback path for `bun upgrade`. If a release regresses something in your project, the documented recovery is to install a specific version through one of the install methods, not to run an undo command. Pin your version in CI for that reason.

The larger limitation is the compatibility promise itself. "Drop-in replacement" is the README's phrase, and the docs carry a Node.js compatibility page precisely because the surface is large. Anything that reaches below the JavaScript API, native addons, unusual process and signal semantics, or internals that libraries poke at, is where a drop-in claim tends to break first. The README does not enumerate which addons work.

Second, the package manager writes its own lockfile. The repository root contains bun.lock, and the README links a lockfile page in the docs. A team that already has package-lock.json or yarn.lock is choosing between two sources of truth, and the README does not describe a migration path for that.

Third, the bundler is a separate product decision. The README links a page comparing Bun's bundler to esbuild, which tells you the project expects you to be weighing them. If your build already works and produces artifacts you have validated, replacing it buys you nothing except a new failure mode.

Finally, the licence. The repository has a LICENSE.md at the root, but the licence identifier is not stated in the README, so read that file before you ship Bun inside a product.

Bun against Node.js plus npm, and against Vite

The honest comparison is not Bun versus npm. npm is a package manager; Bun is a runtime that happens to include one. If you only want faster installs, `bun install` in an otherwise unchanged Node.js project is the smallest possible experiment, and the README says Bun's tools are "usable in existing Node.js projects with little to no changes". You keep Node.js as the runtime and take the package manager. That is a reversible decision.

Against Vite the difference is architectural. Vite is a dev server and build tool that sits on top of Node.js and uses esbuild and Rollup for transformation and bundling. Bun replaces the runtime underneath instead, and its bundler is a Rust crate in the same binary rather than a dependency. Vite's plugin ecosystem is built around its own hook API; Bun's bundler has its own plugin and loader system, documented separately, so plugins are not portable between them. If your build depends on a Vite plugin you cannot replace, the bundler half of Bun is not available to you even if the runtime half is.

Against plain Node.js with tsx or ts-node, Bun's advantage is that TypeScript and JSX need no loader configuration at all. The cost is that you are running on JavaScriptCore rather than V8, and any behaviour that differs between engines becomes your problem to find.

Release cadence, upgrades and what they cost you

The release list shows bun-v1.4.0 on 2026-08-20, bun-v1.3.14 on 2026-05-13 and bun-v1.3.13 on 2026-04-20. The last push to the repository was on 2026-08-20, and the repository is not archived. The gap between 1.3.14 and 1.4.0 is roughly three months, and the patch releases inside the 1.3 line landed about three weeks apart.

That cadence has a practical consequence. `bun upgrade` moves you to the latest release, and the README separately documents a canary channel built from every commit to main. A team that runs `bun upgrade` in CI without pinning is testing against whatever shipped that week. The documented way to stay on canary is `bun upgrade --canary`, which is opt-in, so the default channel is the stable release line.

Upgrade cost is mostly in the runtime, not the package manager. A lockfile format change or a resolution change is visible immediately in a diff; a change in JavaScriptCore behaviour or in Node.js compatibility is visible only when a test fails or, worse, when it does not. That asymmetry is the argument for running your existing test suite under `bun test` before you switch anything in production.

On licensing: the repository ships LICENSE.md at the root, and the licence identifier is not stated in the README. If you redistribute Bun, or embed it in a product, read that file and get your own advice. Nothing in the README addresses licensing.

Editorial conclusion

Adopt Bun if you want one binary to run TypeScript, install packages and execute tests, and you are willing to run `bun install` against a copy of an existing Node.js project before committing to it. Do not adopt it if your production runtime must stay byte-for-byte Node.js, or if you depend on native addons that the Node.js compatibility page does not list as supported. Verify three things first: that your target platform meets the CPU requirements linked from the installation page, that your lockfile story is settled (Bun writes bun.lock, not package-lock.json), and that `bun test` discovers the same test files your current runner does.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes