Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 39 ยท Deploy and Compatibility

Node.js Compatibility and Migrating a Project

What works the same in Bun and Node: built-in modules, npm packages, CommonJS and ESM, globals and import.meta. Learn the differences and migrate a Node project step by step.

Bun was designed as a drop-in replacement for Node.js: most Node programs and npm packages run unchanged. Under the hood Bun uses a different engine (JavaScriptCore, the engine of Safari, instead of V8) and its own implementations of the Node standard library written in native code. "Mostly compatible" is not "identical", so a careful migration beats a hopeful one. This lesson shows what to expect and how to switch a real project safely.

Bun is not available on this site, so Bun commands are read-only. The runnable blocks run on Node 24 and show code that behaves the same on both runtimes, including how to detect which one you are on.

What works out of the box

  • Built-in modules with the node: prefix: node:fs, node:path, node:os, node:http, node:https, node:net, node:crypto, node:stream, node:events, node:util, node:url, node:zlib, node:child_process, node:worker_threads, node:readline, node:assert, node:test (a compatible subset) and more. Always import with the node: prefix; it is clearer and works everywhere.
  • Globals: process, Buffer, setTimeout, fetch, URL, TextEncoder, AbortController, structuredClone, console, __dirname and __filename (also in ESM).
  • Module systems: ES modules (import) and CommonJS (require) both work, and can be mixed in one project. Top-level await works. File extensions .ts, .tsx, .jsx run with no build step.
  • npm packages: bun install reads package.json and the npm registry, so Express, Fastify, Prisma, Zod and thousands more are installable. package.json fields like exports, main and module are honored.
  • Native add-ons using Node-API (.node files) are supported, so many packages with native code work.

An Express app, for instance, can run unchanged with bun run server.js, because Express uses node:http, which Bun implements. Bun.serve is faster and nicer for new code, but you do not have to rewrite on day one.

Differences to know

Area Node Bun
Engine V8 JavaScriptCore (different performance profile, same language)
TypeScript / JSX needs a build step or a flag runs directly
.env files needs dotenv or --env-file loaded automatically
Test runner node:test bun test (Jest-compatible)
Package manager npm bun install (also works with npm projects)
Lockfile package-lock.json bun.lock (text)
Process model cluster module cluster is limited; use reusePort or several processes
Some modules node:vm, node:inspector, node:v8 fully partial or different

Some other gotchas: process.version reports a Node-compatible version for libraries that check it, while process.versions.bun holds the real Bun version. Source maps, stack trace formats and uncaught-error output differ. Some packages that poke at V8 internals (v8.getHeapStatistics, --inspect tooling) behave differently. Timing and ordering of microtasks and process.nextTick are tuned to match Node, but extremely subtle code can still differ. The authoritative list of per-module support is in Bun's documentation page on Node.js compatibility: check it for modules your app depends on, and test.

Detecting the runtime

Libraries that must run on both can feature-detect:

TypeScript
const isBun = typeof Bun !== "undefined";
const isNode = !isBun && typeof process !== "undefined" && !!process.versions?.node;

if (isBun) {
  console.log("Bun", Bun.version);
} else if (isNode) {
  console.log("Node", process.versions.node);
}

Prefer checking for the capability (typeof Bun?.file === "function") over checking the runtime name, so your code also works in a future runtime that copies the API. In TypeScript, install the types with bun add -d @types/bun so that Bun and bun:test type-check.

Node.js Runtime-agnostic code: detect, then adapt

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Migrating a Node project: a safe path

  1. Install Bun and check bun --version. Keep Node installed while you migrate.
  2. Work on a branch. Run bun install in the project. Bun reads package-lock.json and creates bun.lock with matching versions. Commit the new lockfile and delete the old one once everything passes, so CI uses a single package manager.
  3. Run your tests with the old runner first (npm test) to record a baseline. Then run them under Bun. If you use Jest, bun test understands most of the API: change imports from @jest/globals to bun:test where needed, or keep Jest and run it with bun --bun run jest while you evaluate.
  4. Run the app: bun run src/index.ts. Fix what breaks. Typical culprits: a dependency that needs V8-specific APIs, a postinstall script not listed in trustedDependencies, or __dirname assumptions in odd toolchains.
  5. Update scripts. package.json scripts can stay ("start": "node dist/index.js"). When you want Bun for them, bun run start runs the script with Bun's shell. To force a script's node shebang binaries to use Bun's runtime, add the --bun flag: bun --bun run dev.
  6. Replace what you no longer need: dotenv, ts-node, nodemon (use --watch), cross-env and jest/ts-jest often go away.
  7. Update deployment: change the Docker base image and the install and start commands (see Docker and single-file executables).
  8. Roll out gradually: run both runtimes in staging, compare metrics, then switch production. Having a one-line rollback (the Node start command) makes it a low-risk change.

A frequent first step with no risk is to use Bun only as the package manager and test runner while production still runs Node. You gain install speed on day one.

When to stay on Node

Bun is not the right choice if you depend on an unsupported module, require a specific Node version policy (for example long-term-support guarantees from your platform), rely on tools tied to V8 or its inspector protocol, or your host does not offer Bun. Mixed setups are normal: Bun for scripts and tests, Node for the one service that needs it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which JavaScript engine does Bun use?

    Bun is built on JavaScriptCore, the engine from WebKit/Safari; Node uses V8.
  2. 2. How can a library check at runtime whether it is running on Bun?

    The Bun global (and process.versions.bun) only exist on Bun.
  3. 3. What is a low-risk first step when adopting Bun in a Node project?

    Faster installs and tests need no change to the production runtime.
  4. 4. Which import style is recommended for Node's built-in modules?

    The node: prefix is explicit and works on Node and Bun.

Summary

  • Bun implements most of Node's modules and globals and installs npm packages, so many apps run unchanged.
  • Differences include the engine, partial modules (vm, cluster, inspector), .env loading and the lockfile format.
  • Detect capabilities, not runtime names; add @types/bun for types.
  • Migrate on a branch: install, run tests, run the app, update scripts, drop redundant tools, change deployment, roll out gradually.
  • Mixing Bun and Node in one organization is fine.

Next: Docker and Single-File Executables