bun

---
name: bun
description: Use when you want a fast all-in-one JavaScript runtime, package manager, bundler, and test runner to replace Node.js plus npm.
source: https://bun.sh/docs
generated: 2026-07-02T18:41:34.491Z
category: other
audience: engineers
---

## When to use

- Installing dependencies quickly with bun install as a drop-in for npm/yarn/pnpm
- Running scripts, TypeScript, or JSX directly without a separate build step
- Running unit tests with the built-in Jest-compatible bun test runner
- Bundling or transpiling code with bun build for the browser or server

## Key concepts

### All-in-one toolkit

A single binary that is a runtime, package manager, test runner, and bundler. It targets Node.js API compatibility while running TypeScript and JSX natively without extra tooling.

### JavaScriptCore engine

Bun is built on Apple's JavaScriptCore (WebKit) and written in Zig, rather than V8. This is a key difference from Node.js and Deno and contributes to its fast startup and install times.

### bunfig.toml

Bun's optional configuration file. It controls install behavior (registry, lockfile, cache), test settings, runtime flags, and more. Bun also reads .npmrc and package.json for some settings.

### bun.lock

Bun's lockfile. Newer Bun versions use a human-readable text bun.lock by default; older versions wrote a binary bun.lockb. It records the exact resolved dependency tree.

### Native package manager

bun install reads package.json and resolves dependencies into node_modules using a global cache and hardlinks/copies, making repeat installs very fast. Compatible with the npm registry.

## API reference

```
bun install
```

Install all dependencies from package.json, writing node_modules and updating bun.lock.

```
bun install
bun add zod
bun add -d typescript
bun remove zod
```

```
bun run <script|file>
```

Run a package.json script or execute a JS/TS file directly with the Bun runtime.

```
bun run dev
bun run ./src/index.ts
bun index.tsx
```

```
bun test
```

Run the built-in Jest-compatible test runner over *.test.ts and *.spec.ts files.

```
import { test, expect } from "bun:test";

test("adds numbers", () => {
  expect(2 + 2).toBe(4);
});

// then: bun test --watch
```

```
bun build <entry> --outdir <dir>
```

Bundle and transpile JavaScript/TypeScript for the browser or as a runnable executable.

```
bun build ./src/index.ts --outdir ./dist --target browser
bun build ./cli.ts --compile --outfile mycli
```

```
bunx <package>
```

Auto-install and run a package binary without adding it to dependencies (like npx).

```
bunx cowsay "hello"
```

## Gotchas

- Bun uses JavaScriptCore, not V8, so a small number of V8-specific or native Node addons may behave differently or not load
- Node.js API compatibility is high but not 100% — check the docs before assuming a built-in Node module works identically
- Older lockfiles were binary bun.lockb; newer Bun emits text bun.lock — be consistent across a team to avoid churn
- bun run <script> runs package.json scripts, but bare bun <file> runs a file with the runtime; do not confuse the two
- On Windows, support arrived later than macOS/Linux; verify behavior of platform-specific scripts
- bunfig.toml settings can be overridden by .npmrc and CLI flags, so check precedence when installs misbehave

---
Generated by SkillMake from https://bun.sh/docs on 2026-07-02T18:41:34.491Z.
Verify against source before relying on details.

File: ~/.claude/skills/bun/SKILL.md