Node.js Compatibility

Bun implements most Node.js APIs for drop-in compatibility

Bun aims to be a drop-in replacement for Node.js. Most Node.js applications work with Bun with little to no changes. Bun implements the most commonly used Node.js built-in modules and APIs.

Built-in Module Support

Bun implements the following Node.js built-in modules:

Fully Supported

These modules are fully or nearly fully implemented:

node:fs

File system operations (sync and async)

node:path

File path manipulation

node:buffer

Binary data handling

node:stream

Streaming data

node:crypto

Cryptographic operations

node:http

HTTP client and server

node:https

HTTPS client and server

node:net

TCP networking

node:url

URL parsing and formatting

node:util

Utility functions

node:events

Event emitter

node:os

Operating system info

Partially Supported

These modules have most features implemented:

• node:child_process - Spawn processes (use Bun.spawn() for better performance)
• node:dns - DNS lookups
• node:zlib - Compression (use Bun.gzipSync() for better performance)
• node:readline - Command-line input
• node:timers - setTimeout, setInterval
• node:assert - Testing assertions
• node:querystring - Query string parsing
• node:worker_threads - Multi-threading
• node:perf_hooks - Performance monitoring

Not Yet Implemented

These modules are planned but not yet available:

• node:cluster - Load balancing (use Bun.serve() with reusePort)
• node:dgram - UDP sockets (use native UDP in Bun)
• node:vm - Virtual machine
• node:repl - Interactive shell
• node:tty - Terminal control

Import Syntax

Use the node: prefix to import Node.js modules:

import fs from "node:fs";
import { readFile } from "node:fs/promises";
import path from "node:path";

Bun also supports the legacy syntax without node::

import fs from "fs";
import path from "path";

Both syntaxes work identically in Bun.

fs Module

Bun fully implements the node:fs module:

import fs from "node:fs";
import { readFile, writeFile } from "node:fs/promises";

// Synchronous
const data = fs.readFileSync("file.txt", "utf-8");
fs.writeFileSync("output.txt", data);

// Promises
const content = await readFile("file.txt", "utf-8");
await writeFile("output.txt", content);

// Callbacks
fs.readFile("file.txt", "utf-8", (err, data) => {
  if (err) throw err;
  console.log(data);
});

For better performance, use Bun.file() and Bun.write() instead of fs methods.

http and https Modules

Create HTTP servers using Node.js APIs:

import http from "node:http";

const server = http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("Hello from Node.js API");
});

server.listen(3000);

For better performance, use Bun.serve() instead of the http module.

Buffer

Bun implements the Node.js Buffer class:

const buf = Buffer.from("Hello");
console.log(buf.toString("hex"));  // 48656c6c6f

// Buffer methods
Buffer.alloc(10);
Buffer.concat([buf1, buf2]);
Buffer.compare(buf1, buf2);

process

The global process object is available:

process.argv          // Command-line arguments
process.env           // Environment variables
process.cwd()         // Current working directory
process.exit(0)       // Exit process
process.platform      // OS platform
process.version       // Node.js version (emulated)
process.versions.bun  // Bun version

// Events
process.on("exit", (code) => {
  console.log(`Exiting with code ${code}`);
});

process.on("uncaughtException", (err) => {
  console.error("Uncaught exception:", err);
});

__dirname and __filename

These globals are available in CommonJS modules:

console.log(__dirname);   // Directory path
console.log(__filename);  // File path

In ESM, use import.meta:

import.meta.dir    // Same as __dirname
import.meta.path   // Same as __filename

require()

Bun supports require() for CommonJS modules:

const fs = require("node:fs");
const myModule = require("./my-module");

You can also use require() in ESM files for better compatibility:

// This works in Bun
import fs from "node:fs";
const path = require("node:path");

Module Resolution

Bun follows Node.js module resolution rules:

1. Resolve node_modules directories
2. Check package.json "exports" field
3. Try file extensions: .ts, .tsx, .js, .jsx, .json
4. Try index files

Additional Bun features:

• Native TypeScript support (no need for ts-node)
• Automatic JSX transformation
• Import from package.json "module" field

Package.json Compatibility

Bun reads standard package.json fields:

{
  "name": "my-package",
  "version": "1.0.0",
  "main": "./index.js",
  "module": "./index.mjs",
  "types": "./index.d.ts",
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.js"
    }
  },
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^4.18.0"
  }
}

Run scripts with bun run:

bun run start  # Executes with Bun instead of Node.js

Environment Variables

Access environment variables via process.env:

const apiKey = process.env.API_KEY;
process.env.NODE_ENV = "production";

Bun automatically loads .env files. See Environment Variables.

npm Package Compatibility

Bun is compatible with most npm packages:

• ✅ Pure JavaScript packages work without changes
• ✅ Packages with native modules (Node-API/N-API) are supported
• ✅ TypeScript packages work natively
• ⚠️ Packages with node-gyp builds may need recompilation

Performance Comparison

While Bun maintains Node.js compatibility, Bun’s native APIs are often faster:

Operation	Node.js API	Bun Native API
Read file	fs.readFileSync()	Bun.file().text()
Write file	fs.writeFileSync()	Bun.write()
HTTP server	http.createServer()	Bun.serve()
Spawn process	child_process.spawn()	Bun.spawn()
SQLite	better-sqlite3	bun:sqlite
Hash	crypto.createHash()	Bun.hash()

Use Bun’s native APIs for better performance, but Node.js APIs for maximum compatibility.

Migration Guide

To migrate a Node.js project to Bun:

1. Install Bun

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

   bun install
   

   This reads your package.json and installs dependencies.

3. Update scripts

   Replace node with bun in your scripts:

   package.json

   {
     "scripts": {
   -   "start": "node server.js",
   +   "start": "bun run server.js",
     }
   }
   
4. Test your application

   bun run start
   

   Most apps work without changes!

5. Optional: Use Bun APIs

   For better performance, replace Node.js APIs with Bun equivalents:

   server.ts

   - import fs from "node:fs";
   - const data = fs.readFileSync("file.txt", "utf-8");
   + const file = Bun.file("file.txt");
   + const data = await file.text();
   

Known Differences

A few differences exist between Bun and Node.js:

1. Bun is faster: Startup time and runtime performance are significantly better
2. Native TypeScript: No need for ts-node or transpilation
3. Top-level await: Works everywhere, not just ES modules
4. Different engine: JavaScriptCore instead of V8 (rare compatibility issues)

Check Compatibility

To check if a package works with Bun:

1. Check Bun compatibility tracker
2. Try installing and running tests: bun install && bun test
3. Report issues at github.com/oven-sh/bun

Next Steps

Bun APIs

Learn about Bun-specific APIs

Package Manager

Use Bun’s fast package manager

Web APIs

Web standard APIs in Bun

Quickstart

Build your first Bun app