Node.js 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:

Resolve node_modules directories
Check package.json "exports" field
Try file extensions: .ts, .tsx, .js, .jsx, .json
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:

Install Bun

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

Install dependencies

bun install

This reads your package.json and installs dependencies.

Update scripts

Replace node with bun in your scripts:

package.json

{
  "scripts": {
-   "start": "node server.js",
+   "start": "bun run server.js",
  }
}

Test your application

bun run start

Most apps work without changes!

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:

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

Check Compatibility

To check if a package works with Bun:

Check Bun compatibility tracker
Try installing and running tests: bun install && bun test
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

Core Runtime

APIs

HTTP & WebSocket

Data & Storage

System & Process

Utilities

​Built-in Module Support

​Fully Supported

node:fs

node:path

node:buffer

node:stream

node:crypto

node:http

node:https

node:net

node:url

node:util

node:events

node:os

​Partially Supported

​Not Yet Implemented

​Import Syntax

​fs Module

​http and https Modules

​Buffer

​process

​__dirname and __filename

​require()

​Module Resolution

​Package.json Compatibility

​Environment Variables

​npm Package Compatibility

​Performance Comparison

​Migration Guide

​Known Differences

​Check Compatibility

​Next Steps

Bun APIs

Package Manager

Web APIs

Quickstart

Build docs developers (and LLMs) love

Built-in Module Support

Fully Supported

Partially Supported

Not Yet Implemented

Import Syntax

fs Module

http and https Modules

Buffer

process

dirname and filename

require()

Module Resolution

Package.json Compatibility

Environment Variables

npm Package Compatibility

Performance Comparison

Migration Guide

Known Differences

Check Compatibility

Next Steps