Bun 1 3 12

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:

# macOS & Linux
curl -fsSL https://bun.com/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1|iex"

# npm
npm install -g bun

# Homebrew
brew install oven-sh/bun/bun

# Docker
docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun

Verify installation:

bun --version      # e.g. 1.3.12
bun --revision     # exact git commit

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          # latest stable
bun upgrade --canary # latest untested build
bun upgrade --stable # switch back to stable

Usage Examples

Run a file (TypeScript, JSX, TSX supported natively):

bun run index.tsx
bun index.ts         # "naked" form, omit `run`
bun --watch run index.tsx  # watch mode

Run package.json scripts:

{
  "scripts": {
    "dev": "bun server.ts",
    "build": "bun build ./src/index.tsx --outdir ./dist"
  }
}

bun run dev
bun dev              # shorthand (fails if name conflicts with built-in command)

Install packages:

bun install                    # install all dependencies
bun install express            # add a package
bun install -d typescript      # add dev dependency
bun install --production       # skip devDependencies
bun install --frozen-lockfile  # CI mode, exact 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                    # all tests
bun test math               # filter by name
bun test ./math.test.ts     # specific file
bun test --watch            # watch mode
bun test --concurrent       # parallel execution

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