Bun is genuinely faster than Node at the things it owns end to end — process start-up, package installs, its bundler, its test runner — and having all of that in one binary removes real friction from a JavaScript toolchain. Where the two are closest is the case you probably care about most: a long-running HTTP service with a database behind it, where the engine is rarely the bottleneck. Node’s advantage is not speed. It is a published LTS cadence, a native-addon story that every package author already targets, and fifteen years of operations tooling that assumes Node is what is running. For most teams the defensible answer today is to adopt Bun for tooling now, and move the service only after you have proved your own dependency tree and your own p95 under it.
What you’ll accomplish
- Understand why the engine difference — JavaScriptCore in Bun, V8 plus libuv in Node — is the root of most of the behavioural differences between them
- Test Node API compatibility against your actual dependency tree instead of trusting a compatibility claim
- Get a heap snapshot, a CPU profile and a crash artefact out of each runtime, so you can debug the one you pick when it misbehaves at 2am
- Measure start-up time, p95 latency and RSS over a soak on your own workload, instead of on someone else’s hello-world benchmark
- Land on Node, Bun, or “Bun for tooling, Node for the service” with a reason you can write down and defend later
Prerequisites
- A machine where both runtimes can live side by side. Node through
nvmor your distribution’s packages; Bun through its install script or your package manager. - Do not take version numbers from an article, including this one. Check the current Node LTS line on the Node release schedule and the current Bun release on Bun’s own docs before you plan anything; both links are at the end.
- A real workload: your actual test suite, your actual dependency tree, and either staging traffic or a replay of your production request mix. A synthetic route proves nothing about a service that talks to a database.
- Linux is assumed for the operations commands.
/usr/bin/time -vis GNU time and is not on macOS by default, andcoredumpctlis systemd-only; the runtime flags are the same on both. - Enough RAM headroom to soak for hours. GC pacing is a genuine difference between the two, and it does not show up in a 30-second run.
How it works
Node is a C++ program that embeds Google’s V8 engine and uses libuv for its event loop, thread pool and platform I/O. Everything else — package manager, bundler, test runner, TypeScript — is userland that you choose, install and version yourself. Bun is a Zig program that embeds Apple’s JavaScriptCore, implements its own I/O rather than using libuv, and ships the installer, the bundler, the test runner, a SQLite driver and a TypeScript/JSX transpiler inside the same executable.
That engine choice is where most of the observable differences come from. Both are tiered JITs, tuned differently. JavaScriptCore runs a low-level interpreter, a baseline JIT, then two optimising tiers (DFG and FTL); V8 runs Ignition, Sparkplug, then its optimising tiers. JavaScriptCore reaches usable machine code quickly, which flatters processes that live for milliseconds; V8’s top tier has historically been very strong on long steady-state hot loops, which is what a service that has been up for a week is running. The garbage collectors differ too, so two builds of the same app can match on throughput and still draw completely different RSS curves over a multi-hour soak. The engines are not uniformly faster or slower than one another — they are differently shaped, which is why benchmarking your own workload is not optional.
The second axis is the Node API surface. Bun implements the node: builtins and N-API, the stable C ABI that modern native addons target. Coverage is good and improves every release, but it is not complete, and the incomplete parts move — corners of node:cluster, node:vm, node:http2 and worker_threads have all been rough at various points, and anything reaching for V8-specific APIs (the v8 module’s serialisation and heap-snapshot format, process.binding) will not work by construction. Because that gap list changes every release, reading a compatibility table is worth much less than running your own dependency tree through the runtime, which is what the steps below do.
| Node.js | Bun | |
|---|---|---|
| Engine | V8 | JavaScriptCore |
| I/O layer | libuv | Bun’s own, written in Zig |
| TypeScript | Type stripping in recent lines; otherwise tsc, tsx or swc | Executed directly, no build step |
| Package manager | npm, pnpm or yarn — a separate tool | bun install, built in |
| Test runner | node --test, or jest/vitest | bun test, built in |
| Bundler | esbuild, rollup, rspack — a separate tool | bun build, built in |
| SQLite | node:sqlite in recent lines | bun:sqlite |
| Native addons | N-API and the V8 API, plus node-gyp and prebuilds | N-API; addons linking V8 symbols will not load |
| Heap snapshot | --heapsnapshot-signal, v8.writeHeapSnapshot() | generateHeapSnapshot() from bun:jsc |
| CPU profile | --cpu-prof, or the inspector | The inspector via --inspect |
| Fatal-error artefact | Diagnostic report via --report-on-fatalerror | OS core dump plus the panic trace |
| Support window | Published LTS schedule with security backports | Frequent releases; no comparable published LTS window |
| Process managers, agents, APM | Assume Node; universally exercised | Improving, far less widely exercised |
Step-by-step
1. Install both without disturbing the system runtime. Keep them independent so you can flip between them per shell.
nvm install --lts && nvm use --lts
curl -fsSL https://bun.sh/install | bash
node --version && bun --version
You should get two version strings. If bun is not found, your shell profile has not picked up ~/.bun/bin yet — open a new shell.
2. Inventory the native addons before you do anything else. This is the single most common reason a migration stalls, and it takes 20 seconds to find out.
find node_modules -maxdepth 3 -name binding.gyp -print
find node_modules -name '*.node' -print | head -40
Every binding.gyp is a package that compiles against Node headers with node-gyp; every .node file is a compiled addon that was either built locally or downloaded as a prebuilt binary. If those packages use N-API they have a good chance under Bun. If they link V8 symbols directly, they do not, and no amount of configuration changes that.
3. Probe every declared dependency under both runtimes. Write the probe once and run it twice — it is the same file, and it uses only APIs both runtimes implement.
// probe.mjs — try to load every declared dependency under whichever runtime runs this
import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const pkg = require(process.cwd() + "/package.json");
const deps = Object.keys({ ...pkg.dependencies, ...pkg.optionalDependencies });
let failed = 0;
for (const name of deps) {
try {
await import(name);
console.log("ok " + name);
} catch (err) {
failed++;
console.log("FAIL " + name + " — " + err.message);
}
}
process.exit(failed ? 1 : 0);
node probe.mjs; echo "node exit=$?"
bun probe.mjs; echo "bun exit=$?"
Both should print exit=0. Any FAIL line under Bun that passes under Node is a concrete, named blocker — not a rumour about compatibility. Keep the list; it is the actual scope of your migration.
4. Run the real test suite, not just Bun’s. bun test runs Bun’s own runner and will not understand a jest or vitest configuration. To run your existing suite on the Bun runtime, keep your runner and force the interpreter.
bun install --frozen-lockfile
bun --bun run test
--bun tells Bun to ignore a #!/usr/bin/env node shebang in the runner’s binary and execute it on Bun instead. If the suite passes here and fails under plain bun test, that is a test-runner difference, not a runtime one — worth knowing which you are looking at.
5. Measure the three numbers that actually decide this. Start-up time, tail latency on a realistic route, and memory over a soak.
# start-up: a real entrypoint that exits, not a version flag
hyperfine --warmup 5 'node dist/main.js --selftest' 'bun src/main.ts --selftest'
# tail latency: your real route, real database, real request mix
oha -z 60s -c 100 http://127.0.0.1:3000/api/things
# memory over a soak: leave this running for hours, not minutes
while :; do ps -o rss= -p "$SERVICE_PID"; sleep 30; done | tee rss.log
Read p95 and p99, not the mean — the mean hides exactly the GC pauses you are comparing. Read rss.log as a curve: a service that plateaus is fine, one that climbs for six hours is not, on either runtime.
6. Prove you can debug it in production before you put it there. This is the part teams skip and regret.
# Node: heap snapshot on demand, CPU profile, report on fatal error
node --heapsnapshot-signal=SIGUSR2 --report-on-fatalerror \
--report-directory=/var/log/app dist/main.js
kill -USR2 "$SERVICE_PID" # writes Heap.<pid>.<seq>.heapsnapshot to cwd
node --cpu-prof --cpu-prof-dir=./prof dist/main.js
// bun-heap.ts — Bun's equivalent, triggered however you like
import { generateHeapSnapshot } from "bun:jsc";
process.on("SIGUSR2", async () => {
await Bun.write("heap.json", JSON.stringify(generateHeapSnapshot(), null, 2));
console.log("wrote heap.json");
});
Node gives you a .heapsnapshot you open in Chrome DevTools and a JSON diagnostic report when the process dies badly. Bun gives you a JavaScriptCore snapshot in a different format, an inspector you attach with bun --inspect, and for a hard crash an OS core dump plus a panic trace — so confirm ulimit -c unlimited and kernel.core_pattern are set on the host before you need them. Hunting a leak with heap snapshots walks through the workflow on the Node side.
7. Put it under a process manager and in a container. Both need to survive a restart, a SIGTERM, and an image rebuild.
FROM oven/bun:1 AS runtime
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production
COPY . .
USER bun
CMD ["bun", "src/main.ts"]
[Service]
ExecStart=/usr/local/bin/bun /app/src/main.ts
Restart=on-failure
KillSignal=SIGTERM
TimeoutStopSec=30
Verify graceful shutdown explicitly on whichever runtime you choose: send SIGTERM, confirm in-flight requests drain and the process exits before TimeoutStopSec. A supervisor that has to SIGKILL your service every deploy will drop connections regardless of which runtime is underneath.
8. Make the call, and write down why. The tree below is the version we use. It is deliberately biased toward the boring answer for anything with revenue behind it.
Validate it works
Run these against the candidate before anyone calls the migration done.
bun probe.mjs && echo "all declared deps load"
bun --bun run test
bun install --frozen-lockfile && bun pm ls | head -20
curl -fsS -o /dev/null -w '%{http_code} %{time_total}\n' http://127.0.0.1:3000/healthz
kill -TERM "$SERVICE_PID"; sleep 5; ps -p "$SERVICE_PID" || echo "clean shutdown"
You are looking for: probe exit 0, a green suite, an install that does not mutate the lockfile, a 200 from the health check with a plausible time, and a process that is gone after SIGTERM without needing SIGKILL. If any of the five is ambiguous, you do not yet have a result.
Troubleshooting
A dependency loads but behaves differently. Many packages ship a pure-JS fallback that silently activates when the native addon fails to load. Nothing errors; the code is just slower, or produces subtly different output for hashing or image work. Compare a known input/output pair on both runtimes rather than assuming a successful import means a successful load.
Two lockfiles drift apart. If package-lock.json and Bun’s lockfile both live in the repo, CI and your laptop can resolve different transitive versions and you will chase a bug that only exists on one of them. Pick one resolver per repository, run installs with --frozen-lockfile everywhere, and treat an install that rewrites the lockfile in CI as a failure.
A stale bunx cache runs an old binary. bunx caches aggressively and differently from npx, so a tool you “just upgraded” can keep running the previous version. Clear it with bun pm cache rm and re-run.
Memory climbs under one runtime and not the other. This is usually GC pacing, not a leak, and it usually resolves into a plateau if you let the soak run long enough. If it genuinely does not plateau, take a snapshot from each runtime at the same point in the soak and compare retained sets. Bun’s --smol mode reduces memory use at some throughput cost and is worth testing on memory-constrained containers.
It works locally but the container will not start. Usually a native addon compiled against a different libc than the base image provides. Rebuild inside the image rather than copying node_modules in, and keep the builder and runtime stages on the same base.
When this is the wrong approach
If your question is only “which one is faster”, this article cannot answer it and neither can anyone else’s benchmark. The engines are differently shaped, and the difference on your service depends on how much of your request budget is spent in JavaScript versus waiting on a database. Measure it.
Do not rewrite handlers onto Bun.serve() while you are still evaluating. It is fast, and it is Bun-specific — porting back to Node means rewriting that layer under time pressure, which is the worst possible moment. Stay on the Node-compatible HTTP API until the decision is final.
If what you actually want is a runtime with a permissions model and first-class TypeScript rather than raw speed, you are asking a different question — Deno vs Node covers that comparison, and the answer there turns on sandboxing and module resolution rather than on engine internals.
And the honest disclosure: Stack Harbor has a bias here, worth naming. We are an MSP — when a service we manage breaks at 03:00, we are the ones awake for it, and the fix has to exist. That makes us weight the length of the support tail more heavily than a team shipping a product they will rewrite in eighteen months should. A published LTS line with security backports means a patch arrives on a schedule we can plan around; on a fast-moving project the fix may well be excellent and land the same week, but we cannot give a client a date for it. That is a supportability argument, not a performance one, and if you carry your own pager you are entitled to weigh it differently than we do.
Both projects document their own state better than any third party can: Bun’s documentation at bun.sh/docs is the authority on what is implemented this release, and the Node.js release schedule is the authority on which lines are supported and for how long. Check both before you commit, and re-check the Bun side each time you revisit the decision.
If this is the kind of work you’d rather never own again, it’s the daily job of Managed Cloud Ops — book an infrastructure review.