keepcalculator

06 Numbers and Powers

Bun vs Node.js: What Changes & What to Check First

Card No. 06·82486 · Updated · Standard formula, shown below

Switching from Node.js to Bun changes your runtime, package manager, and many built-in APIs, so the first things to check are your native modules, environment variables, and any code that relies on Node.js-specific globals or streaming behavior. Bun is a drop-in replacement for most Node.js projects, but it has its own module resolution, built-in TypeScript support, and a different HTTP server, so a few compatibility checks before you migrate will save you hours of debugging.

Background: What Bun Actually Is

Bun is a JavaScript runtime written in Zig, first released in 2022 by Jarred Sumner. It was designed to be a faster alternative to Node.js, bundling a runtime, package manager, and bundler into one executable. Unlike Node.js, which uses V8, Bun uses JavaScriptCore (the same engine that powers Safari). That engine difference alone explains many of the behavioral changes you’ll notice.

Bun also includes a built-in test runner, a native bundler, and a package manager that reads the same package.json but uses a global cache. It aims to be compatible with most npm packages, but it’s not a 100% drop-in replacement. The project is still evolving rapidly, so some Node.js features are implemented partially or with different semantics.

Key Changes You’ll Notice Immediately

When you run your existing Node.js app with bun run, the first thing you’ll notice is speed: cold starts and script execution are dramatically faster. But beyond speed, there are several behavioral differences:

  • Module resolution: Bun uses its own resolver that supports TypeScript, JSX, and JSON imports natively. It also respects the "exports" field in package.json, but it may resolve differently than Node.js in edge cases (e.g., self-referencing packages).
  • Globals: Bun provides Bun global with extra APIs (like Bun.file() and Bun.write()), but it also implements most Node.js globals (process, Buffer, setImmediate). However, some are not yet fully implemented (e.g., process.binding is not available).
  • HTTP server: Bun’s native Bun.serve() is not the same as Node’s http module. While Bun can run Express or Fastify, it has its own optimized server that you might want to use for new code.
  • Streams: Node.js streams are supported, but Bun’s native streams are different. Some stream methods like pipe() work, but backpressure handling can differ, especially with large files.
  • Environment variables: Bun loads .env files automatically, but it also supports BUN_ENV and has a different order of precedence. If your code relies on process.env being populated by a specific file, check that.

What to Check First Before Migrating

Before you switch, run this checklist to avoid the most common pitfalls:

  1. Native modules: Any package that uses native code (e.g., bcrypt, sharp, node-canvas) may not have prebuilt binaries for Bun. Check if the package supports Bun or if you need to compile from source.
  2. Node.js built-in modules: Bun implements most of them, but some are incomplete. Test your use of crypto, fs, net, and zlib early.
  3. TypeScript configuration: Bun reads tsconfig.json but ignores some options (like paths in certain contexts). If you use path aliases, verify they work.
  4. Global variables: Check if your code uses __dirname, __filename, or require. Bun supports them in CommonJS, but in ESM you’ll need to use import.meta.dir.
  5. Testing frameworks: If you use Jest or Mocha, Bun’s built-in test runner is different. Your existing test setup may need changes.
  6. Package manager scripts: If you use npm scripts, Bun runs them with bun run, but it doesn’t support all npm lifecycle hooks (like preinstall).

How to Migrate Step by Step

A safe migration path is to start with a small, non-critical service. Here’s a practical sequence:

  1. Install Bun on your machine or CI.
  2. Run bun install to install dependencies. This will create a bun.lockb file. If you need to keep package-lock.json for other tools, you can commit both, but be aware that they may diverge.
  3. Try running your existing test suite with bun test. Fix any failures that are due to runtime differences.
  4. Start your server with bun run start and check logs for warnings about unimplemented APIs.
  5. Gradually replace Node-specific code with Bun alternatives where beneficial (e.g., Bun.serve() instead of http.createServer()).
  6. Monitor performance and memory usage. Bun’s garbage collection and memory layout differ from V8, so you might need to tune your app.

Common Problems and How to Solve Them

Here are the most frequent issues developers hit when switching:

  • Cannot find module ‘./x.ts’ – Bun resolves TypeScript files natively, but if you have a file with a .js extension that imports a .ts file, it may fail. Use explicit extensions.
  • Error: Not implemented: net.Server.prototype.ref() – Some Node.js APIs are not implemented. Check the Bun compatibility page and use a polyfill or alternative.
  • Environment variables not loading – Bun loads .env but not .env.local by default. Use --env-file flag or Bun.env.
  • Worker threads not working – Bun supports Worker but with a different API. If you use worker_threads, test carefully.
  • Memory leaks with streams – Bun’s stream implementation is newer; if you see high memory usage, try using Bun.file() for file operations.

Comparing Performance and Compatibility

Bun is often 2-3x faster than Node.js in server-side rendering and cold start benchmarks, but real-world performance depends on your workload. For CPU-heavy tasks, Bun’s JavaScriptCore can be slower than V8 in some cases. Compatibility is the bigger trade-off: while Bun supports most npm packages, some advanced Node.js features (like async_hooks or vm) are not fully implemented. If your project relies on those, you may need to stick with Node.js or wait for Bun to catch up.

Costs and Risks of Switching

There’s no monetary cost to using Bun (it’s open-source), but there is a migration cost: time spent fixing compatibility issues, retraining your team, and potentially rewriting parts of your codebase. The risk is that Bun is still pre-1.0 (as of 2025), so APIs can change. If you’re building a long-term project, weigh the speed benefits against the stability of Node.js, which has a massive ecosystem and a clear LTS schedule.

Alternatives to Bun

If Bun’s compatibility gaps are a dealbreaker, consider these alternatives:

  • Node.js with a faster package manager – Use pnpm or Yarn PnP to speed up installs while keeping Node’s runtime.
  • Deno – Another modern runtime with built-in TypeScript and security features, but it has its own compatibility issues.
  • Node.js with a bundler – Use esbuild or SWC to speed up module loading without changing the runtime.

Frequently Asked Questions

Is Bun a drop-in replacement for Node.js?

Mostly, but not fully. Bun implements a large portion of Node.js APIs, but some are incomplete or behave differently. For simple scripts and web servers, you can often run without changes. For complex apps with native modules or advanced Node features, you’ll need to test and patch.

Will my existing npm packages work with Bun?

Most pure JavaScript packages work fine. Packages with native bindings may not have prebuilt binaries for Bun, so you may need to compile them from source or find alternatives. Check the package’s documentation for Bun support.

How do I handle environment variables in Bun?

Bun automatically loads .env files, but you can also use Bun.env to access them. For multiple files, use --env-file flag. The precedence is: actual environment variables > .env.local > .env.

Can I use Bun with Express or other Node.js frameworks?

Yes, Bun can run Express, Fastify, Koa, and most other frameworks. However, you won’t get the full speed benefit unless you use Bun’s native Bun.serve(). Some frameworks have known issues with Bun, so test your routes thoroughly.

Does Bun support TypeScript out of the box?

Yes, Bun can run TypeScript files directly without a separate compilation step. It also supports JSX and TSX. However, it doesn’t type-check; it strips types and runs the code. For type checking, you still need tsc.

What happens to my npm scripts when I switch to Bun?

You can run them with bun run instead of npm run. Bun supports most script features, but some npm lifecycle hooks (like preinstall) are not executed. You may need to manually run those steps.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →