Skip to main content
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 / npmBun
npm installbun 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

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
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.
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.
Bun uses Node.js module resolution by default. If a package is not found, run bun install to ensure all dependencies are present.

Build docs developers (and LLMs) love

Get started for freeTalk to us