Bun 1.3.12
Overview
Bun is an all-in-one toolkit for JavaScript and TypeScript applications. It ships as a single, dependency-free executable called bun and includes four integrated tools:
- Runtime — A fast JavaScript runtime designed as a drop-in replacement for Node.js. Written in Zig and powered by Apple's JavaScriptCore engine, Bun starts up ~4x faster than Node.js with lower memory usage.
- Package Manager — A Node.js-compatible package manager up to 25x faster than
npm install, with global caching, workspaces, overrides, and lockfile support.
- Test Runner — A Jest-compatible, TypeScript-first test runner with snapshots, DOM testing, watch mode, and concurrent execution.
- Bundler — A native bundler for JavaScript/TypeScript/JSX/CSS with code splitting, plugins, HTML imports, and hot reloading.
Bun supports TypeScript (.ts), TSX (.tsx), JSX (.jsx), and JavaScript (.js) out of the box with zero configuration. Every file is transpiled on the fly by Bun's fast native transpiler before execution.
When to Use
- Building high-performance JavaScript/TypeScript applications that need faster startup and runtime than Node.js
- Migrating from npm/yarn/pnpm to a faster package manager
- Bundling JavaScript/TypeScript projects for browser or server deployment without webpack or esbuild
- Running Jest-compatible tests with native TypeScript support
- Developing full-stack applications with
Bun.serve HTTP server
- Using built-in SQLite, Redis, WebSockets, TCP/UDP, DNS, and FFI APIs
- Working with native file I/O, streams, binary data, and WebAssembly
- Running CLI tools via
bunx (equivalent to npx, ~100x faster)
Core Concepts
Single Binary: Bun ships as one executable — no separate installs for runtime, package manager, bundler, or test runner. The same bun command handles everything.
JavaScriptCore Engine: Unlike Node.js (V8), Bun uses Apple's JavaScriptCore, the engine behind Safari. This provides faster startup times and lower memory usage while maintaining Web-standard API compatibility.
Zero-Config TypeScript: .ts, .tsx, .jsx files execute directly — no tsc, Babel, or build step needed. Bun transpiles on the fly. For type checking, install @types/bun as a dev dependency.
Node.js Compatibility: Bun implements Node.js globals (process, Buffer, __dirname) and built-in modules (fs, http, path, stream, zlib, etc.) for drop-in compatibility with existing npm packages. Full compatibility is an ongoing effort.
Web Standard APIs: Bun natively implements fetch, WebSocket, ReadableStream, Headers, URL, Crypto, and other Web APIs — no polyfills needed.
ESM-First with CommonJS Support: Bun recommends ES modules but fully supports CommonJS for backward compatibility with the npm ecosystem.
Installation / Setup
Install via script (recommended), package manager, or Docker:
curl -fsSL https://bun.com/install | bash
powershell -c "irm bun.sh/install.ps1|iex"
npm install -g bun
brew install oven-sh/bun/bun
docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun
Verify installation:
bun --version
bun --revision
If command not found, add ~/.bun/bin to your PATH:
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
Upgrade Bun:
bun upgrade
bun upgrade --canary
bun upgrade --stable
Usage Examples
Run a file (TypeScript, JSX, TSX supported natively):
bun run index.tsx
bun index.ts
bun --watch run index.tsx
Run package.json scripts:
{
"scripts": {
"dev": "bun server.ts",
"build": "bun build ./src/index.tsx --outdir ./dist"
}
}
bun run dev
bun dev
Install packages:
bun install
bun install express
bun install -d typescript
bun install --production
bun install --frozen-lockfile
HTTP server with Bun.serve:
const server = Bun.serve({
port: 3000,
routes: {
"/": () => new Response("Hello!"),
"/api/:id": req => new Response(`User ${req.params.id}`),
"/api/posts": {
GET: () => new Response("List posts"),
POST: async req => Response.json({ created: true, ...(await req.json()) }),
},
},
});
console.log(`Listening on ${server.url}`);
Bundle for browser:
bun build ./src/index.tsx --outdir ./dist --target browser --minify
Run tests:
bun test
bun test math
bun test ./math.test.ts
bun test --watch
bun test --concurrent
Advanced Topics
Runtime & Core: File execution, watch mode, bunfig.toml configuration, REPL, debugger → Runtime & Core
HTTP Server & Networking: Bun.serve routing, WebSockets, TLS, TCP/UDP sockets, DNS resolution → HTTP & Networking
Package Manager: Install, add, remove, update, bunx, workspaces, catalogs, overrides, lockfiles, publishing → Package Manager
Bundler: bun build CLI and JS API, entrypoints, targets, formats, plugins, loaders, full-stack HTML imports → Bundler
Test Runner: Jest-compatible API, lifecycle hooks, snapshots, mocking, coverage, CI/CD integration → Test Runner
Data & Storage: SQLite (bun:sqlite), Redis client, file I/O (Bun.file, Bun.write), streams, binary data, S3 → Data & Storage
Process & System: Shell scripting ($ template literal), child processes (Bun.spawn), workers, environment variables, cron → Process & System
Interop & Utilities: FFI (bun:ffi), Node-API modules, C compiler, transpiler API, hashing, glob, semver, TOML/YAML/JSON5 → Interop & Utilities
Node.js Compatibility: Built-in module support status, globals, migration guidance → Node.js Compatibility
