Step-by-Step: Migrating from Node.js 21 to Bun 1.2 for Your Backend APIs

Why Migrate to Bun 1.2?

Bun 1.2 is a modern JavaScript runtime built for speed, offering native TypeScript support, a built-in bundler, test runner, and package manager. Compared to Node.js 21, Bun delivers up to 3x faster startup times, lower memory usage, and seamless compatibility with most Node.js APIs. For backend APIs, this translates to reduced infrastructure costs, faster response times, and simpler tooling.

Pre-Migration Checklist

Before starting the migration, complete these checks to avoid roadblocks:

• Audit all dependencies: Use bun audit or check the Bun Node.js Compatibility page to confirm support for critical packages.
• Back up your Node.js 21 project: Create a separate branch or snapshot to revert if needed.
• Note Node-specific implementations: Identify uses of __dirname, __filename, or custom Node core module polyfills that may need adjustment.

Step 1: Install Bun 1.2

Install Bun on your local machine or CI environment using the official installer:

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

Verify the installation by checking the version:

bun --version
# Should output 1.2.x

Step 2: Initialize Bun in Your Project

Navigate to your existing Node.js 21 project directory. If you don't have a bunfig.toml configuration file, create one to customize Bun's behavior:

# bunfig.toml
[install]
# Use Bun's package manager instead of npm
registry = "https://registry.npmjs.org"

[test]
# Configure test runner settings
preload = ["./test/setup.ts"]

Update your package.json to set the project type to ESM (Bun works with CommonJS, but ESM is preferred for better compatibility):

{
  "type": "module",
  "scripts": {
    "start": "bun run src/index.ts",
    "test": "bun test"
  }
}

Step 3: Migrate Dependencies

Replace npm install with Bun's built-in package manager to install dependencies:

bun install

Bun will read your existing package.json and package-lock.json/yarn.lock, then generate a bun.lockb binary lockfile. If any dependencies throw errors, check for Bun-compatible alternatives or update to the latest version of the package.

Step 4: Adjust Code for Bun Compatibility

Most Node.js 21 code works in Bun out of the box, but a few adjustments may be needed:

ESM Migration

If you're using CommonJS require() syntax, switch to ESM import statements:

// Before (CommonJS)
const express = require("express");
const { PORT } = require("./config");

// After (ESM)
import express from "express";
import { PORT } from "./config.js"; // Note .js extension for ESM imports

Node-Specific APIs

Replace __dirname and __filename (not available in ESM) with Bun-compatible alternatives:

// Before (Node.js CJS)
console.log(__dirname);

// After (Bun ESM)
import { fileURLToPath } from "url";
import { dirname } from "path";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

Bun also supports process.env for environment variables, but you can also use the faster Bun.env alias:

const port = Bun.env.PORT || 3000;

Step 5: Update API-Specific Logic

If you're using Express for your APIs, it will work in Bun, but you can also migrate to Bun-optimized frameworks like Elysia for better performance:

// Elysia example (Bun-native)
import { Elysia } from "elysia";

const app = new Elysia()
  .get("/", () => "Hello from Bun 1.2!")
  .listen(3000, () => {
    console.log("Server running on port 3000");
  });

For ORMs like Prisma or Drizzle, update the database connection to use Bun's native drivers (e.g., bun:sqlite for SQLite, or standard PostgreSQL/MySQL drivers that work with Bun).

Step 6: Test Your Migrated APIs

Bun includes a built-in test runner compatible with Jest syntax. Update your test scripts to use bun test:

# Run all tests
bun test

# Run specific test file
bun test src/__tests__/api.test.ts

Validate API endpoints manually using curl or Postman:

curl http://localhost:3000/api/users

Run your full integration test suite to confirm no regressions.

Step 7: Optimize for Bun

Replace Node.js-specific implementations with Bun's native APIs for better performance:

• Use Bun.serve() for HTTP servers instead of http.createServer() if not using a framework.
• Use Bun.file() and Bun.write() for file operations instead of fs module polyfills.
• Remove unnecessary Node.js shims or polyfills (e.g., node-fetch is redundant since Bun has a built-in fetch API).

Step 8: Deploy to Production

Update your deployment pipeline to use Bun 1.2:

• Docker: Use the official Bun image in your Dockerfile:
  

  FROM oven/bun:1.2
  WORKDIR /app
  COPY package.json bun.lockb ./
  RUN bun install
  COPY . .
  EXPOSE 3000
  CMD ["bun", "run", "src/index.ts"]
  

• Cloud Providers: Use Bun-supported platforms like Fly.io, Railway, or Render, which have native Bun runtime support.

• CI/CD: Update GitHub Actions or GitLab CI to install Bun instead of Node.js 21 before running build and test steps.

Common Pitfalls to Avoid

• Forgetting to set "type": "module" in package.json when migrating to ESM.
• Using Node.js core modules that are not yet supported in Bun (check the compatibility docs first).
• Skipping thorough testing: Always validate in a staging environment before rolling out to production.

Conclusion

Migrating from Node.js 21 to Bun 1.2 is a straightforward process for most backend APIs, with minimal code changes required. You'll gain faster performance, simpler tooling, and access to Bun's growing ecosystem of native tools. Start with a small, non-critical API to test the process, then roll out to larger services once you're comfortable with the workflow.