Migrating from Node.js

Replace Node.js with Bun as a drop-in runtime. Most projects require only a few command substitutions and no code changes.

Bun is designed to be a drop-in replacement for Node.js. It implements nearly the same set of APIs, runs .js, .ts, .jsx, and .tsx files natively, and is compatible with the npm ecosystem. Most projects work with Bun after a handful of command substitutions.

Step-by-step migration

1. Install Bun

   Install Bun on macOS, Linux, or Windows:

   # macOS and Linux
   curl -fsSL https://bun.sh/install | bash
   
   # Windows
   powershell -c "irm bun.sh/install.ps1 | iex"
   

   Verify the installation:

   bun --version
   
2. Replace npm scripts with Bun equivalents

   The most common command substitutions:

   Node.js / npm	Bun
   npm install	bun install
   npm install <pkg>	bun add <pkg>
   npm install -D <pkg>	bun add -d <pkg>
   npm uninstall <pkg>	bun remove <pkg>
   npm run <script>	bun run <script> or bun <script>
   node <file>	bun <file>
   npx <package>	bunx <package>

   Update the scripts in your package.json to use Bun:

   package.json

   {
     "scripts": {
       "dev": "bun run src/index.ts",
       "build": "bun build src/index.ts --outdir dist",
       "test": "bun test"
     }
   }
   
3. Run bun install

   Replace your existing lockfile with Bun’s:

   bun install
   

   Bun automatically converts package-lock.json or yarn.lock to bun.lock, preserving your existing resolved dependency versions.

4. Replace node with bun in CI/CD scripts

   In GitHub Actions or other CI systems, substitute node and npm with bun:

   .github/workflows/ci.yml

   - uses: oven-sh/setup-bun@v2
     with:
       bun-version: latest
   
   - run: bun install
   - run: bun test
   - run: bun run build
   

TypeScript support

Bun runs TypeScript natively — no ts-node, tsx, or compilation step required. For type checking, install @types/bun:

bun add -d @types/bun

Use this recommended tsconfig.json for Bun projects:

tsconfig.json

{
  "compilerOptions": {
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "Preserve",
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true,
    "types": ["bun"]
  }
}

Node.js globals

The following Node.js globals work in Bun without changes:

// Environment variables
process.env.MY_VAR;
Bun.env.MY_VAR; // Bun-native alias

// Buffer
const buf = Buffer.from("hello", "utf8");
buf.toString("base64");

// __dirname and __filename (CommonJS)
console.log(__dirname);
console.log(__filename);

// import.meta (ESM equivalent)
console.log(import.meta.dir);   // equivalent to __dirname
console.log(import.meta.file);  // equivalent to __filename

// process
process.exit(0);
process.argv;
process.cwd();

CommonJS and ESM

Bun supports both CommonJS (require) and ESM (import) in the same project. You do not need to add "type": "module" to package.json — Bun infers the module format from the file extension and package.json fields:

// ESM (preferred)
import { readFile } from "fs/promises";
import data from "./data.json";

// CommonJS also works
const { readFileSync } = require("fs");

When mixing CJS and ESM in the same file, Bun follows the same rules as Node.js. .mjs files are always ESM; .cjs files are always CommonJS.

npm package compatibility

Virtually all packages from the npm registry work with Bun. Packages that rely on Node.js built-in modules (fs, path, crypto, http, etc.) are supported via Bun’s Node.js compatibility layer.

A small number of packages that use native Node.js add-ons (.node files compiled with node-gyp) may not work. Check the Bun Node.js compatibility page for a full list of supported APIs.

Common gotchas

Packages with #!/usr/bin/env node shebang

By default, Bun respects the node shebang and uses the system’s Node.js executable. To force Bun’s runtime, pass --bun:

bun --bun my-script

Dynamic require() in ESM files

If you see require is not defined errors, the file is being treated as ESM. Either rename the file to .cjs or convert to import syntax.

Missing process.env values

Bun loads .env files automatically. You do not need dotenv. If a variable is missing, ensure the .env file is in the project root or use Bun.env.

node_modules resolution

Bun uses Node.js module resolution by default. If a package is not found, run bun install to ensure all dependencies are present.