bun

Category: Development & Coding | Uploader: flora131 | Downloads: 0 | Version: v1.0（Latest）
Use when building, testing, and deploying JavaScript/TypeScript applications. Reach for Bun when you need to run scripts, manage dependencies, bundle code, or test applications with a single unified tool.
Changelog: Source: GitHub https://github.com/flora131/atomic
Directory Structure

Current level: tree/main/.agents/skills/bun/
📄 SKILL.md 11.1 KB
SKILL.md

---
name: bun
description: Use when building, testing, and deploying JavaScript/TypeScript applications. Reach for Bun when you need to run scripts, manage dependencies, bundle code, or test applications with a single unified tool.
metadata:
  mintlify-proj: bun
  version: "1.0"
  internal: true
---

# Bun Skill Reference

## Product Summary

Bun is a unified JavaScript runtime, package manager, bundler, and test runner written in Zig. It replaces Node.js, npm, esbuild, and Jest with a single fast binary. Key files: `bunfig.toml` (configuration), `bun.lock` (lockfile), `package.json` (project metadata). Primary commands: `bun run`, `bun install`, `bun build`, `bun test`. Bun is 4x faster than Node.js on startup and 25x faster than npm for installations. Visit https://bun.com/docs for comprehensive documentation.

## When to Use

Use Bun when:

- **Running scripts**: Execute TypeScript/JavaScript files directly without compilation steps (`bun run file.ts`)
- **Managing dependencies**: Install, add, remove, or update packages faster than npm/yarn/pnpm (`bun install`, `bun add`)
- **Bundling code**: Build JavaScript/TypeScript for browser or server targets with `bun build`
- **Testing**: Run Jest-compatible tests with built-in test runner (`bun test`)
- **Building full-stack apps**: Bundle server and client code together into single executables
- **Monorepo workflows**: Use workspaces and filtering to manage multiple packages
- **Replacing Node.js**: Run any Node.js-compatible code with better performance

Do not use Bun for: type checking (use `tsc` separately), generating type declarations, or projects requiring exact Node.js compatibility for native modules.

## Quick Reference

### Essential Commands

| Task                 | Command                                    | Notes                                              |
| -------------------- | ------------------------------------------ | -------------------------------------------------- |
| Run TypeScript file  | `bun run file.ts`                          | Transpiles on-the-fly; omit `run` for short form   |
| Run package script   | `bun run dev`                              | Executes script from `package.json`                |
| Install dependencies | `bun install`                              | Creates `bun.lock` lockfile                        |
| Add package          | `bun add react`                            | Adds to `dependencies`; use `-d` for dev           |
| Remove package       | `bun remove react`                         | Removes from `package.json` and `node_modules`     |
| Run tests            | `bun test`                                 | Finds `*.test.ts`, `*.spec.ts` files automatically |
| Build bundle         | `bun build ./src/index.ts --outdir ./dist` | Bundles with tree-shaking, minification optional   |
| Watch mode           | `bun --watch run file.ts`                  | Re-runs on file changes                            |
| Create project       | `bun init`                                 | Scaffolds new project with templates               |

### Configuration File: bunfig.toml

Located at project root or `~/.bunfig.toml` (global). Optional but useful for customization.

```toml
[install]
dev = true                    # Install devDependencies
optional = true               # Install optionalDependencies
peer = true                   # Install peerDependencies
linker = "hoisted"           # "hoisted" or "isolated" (pnpm-style)
saveTextLockfile = true      # Use text bun.lock instead of binary

[serve]
port = 3000                  # Default port for Bun.serve()

[test]
root = "."                   # Test root directory
coverage = false             # Enable coverage reporting
timeout = 5000               # Per-test timeout in ms
preload = ["./setup.ts"]     # Scripts to run before tests

[run]
shell = "system"             # "system" or "bun" (Windows defaults to "bun")
bun = true                   # Auto-alias node to bun in scripts
```

### File Types Supported

Bun natively handles: `.js`, `.jsx`, `.ts`, `.tsx`, `.json`, `.jsonc`, `.toml`, `.yaml`, `.html`, `.css`, `.wasm`, `.node`. No configuration needed—just import and use.

### Key Bun APIs

| API              | Purpose           | Example                                     |
| ---------------- | ----------------- | ------------------------------------------- |
| `Bun.serve()`    | Start HTTP server | `Bun.serve({ port: 3000, fetch: handler })` |
| `Bun.file()`     | Read/write files  | `await Bun.file("path.txt").text()`         |
| `Bun.write()`    | Write to disk     | `await Bun.write("out.txt", data)`          |
| `Bun.build()`    | Bundle code       | `await Bun.build({ entrypoints, outdir })`  |
| `Bun.Transpiler` | Transpile code    | `new Bun.Transpiler({ loader: "tsx" })`     |
| `Bun.spawn()`    | Run child process | `Bun.spawn(["ls", "-la"])`                  |

## Decision Guidance

### When to Use Hoisted vs Isolated Linker

| Scenario                      | Use        | Reason                                            |
| ----------------------------- | ---------- | ------------------------------------------------- |
| New monorepo/workspaces       | `isolated` | Prevents phantom dependencies, stricter isolation |
| New single-package project    | `hoisted`  | Traditional npm behavior, simpler                 |
| Existing project (pre-v1.3.2) | `hoisted`  | Backward compatibility                            |
| Migrating from pnpm           | `isolated` | Matches pnpm's approach                           |

Set in `bunfig.toml`: `linker = "isolated"` or via CLI: `bun install --linker isolated`

### When to Use bun build vs bun run

| Use Case                    | Tool                      | Why                                  |
| --------------------------- | ------------------------- | ------------------------------------ |
| Execute TypeScript directly | `bun run`                 | Fast transpilation, no output files  |
| Prepare for production      | `bun build`               | Minification, tree-shaking, bundling |
| Ship single executable      | `bun build --compile`     | Creates standalone binary            |
| Development server          | `bun run` + `Bun.serve()` | Hot reload, fast iteration           |

### When to Use --concurrent in Tests

| Scenario                | Use `--concurrent` | Reason                                        |
| ----------------------- | ------------------ | --------------------------------------------- |
| Independent async tests | Yes                | Parallel execution speeds up suite            |
| Tests with shared state | No                 | Use `test.serial()` for order-dependent tests |
| Database/API tests      | Maybe              | Only if tests don't interfere                 |
| Unit tests              | Yes                | Usually safe and faster                       |

## Workflow

### 1. Initialize a Project

```bash
bun init my-app
cd my-app
```

Choose template: Blank, React, or Library. Creates `package.json`, `tsconfig.json`, `.gitignore`.

### 2. Install Dependencies

```bash
bun install
```

Reads `package.json`, downloads packages, creates `bun.lock`. Much faster than npm.

### 3. Add Packages

```bash
bun add react
bun add -d @types/react typescript
```

Updates `package.json` and `bun.lock` automatically.

### 4. Write and Run Code

```bash
# Create index.ts
echo "console.log('Hello Bun!')" > index.ts

# Run it
bun run index.ts
```

Bun transpiles TypeScript on-the-fly; no build step needed.

### 5. Create HTTP Server

```typescript
// server.ts
const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello!");
  },
});
console.log(`Listening on ${server.url}`);
```

```bash
bun run server.ts
```

### 6. Write Tests

```typescript
// math.test.ts
import { test, expect } from "bun:test";

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

```bash
bun test
```

Finds and runs all `*.test.ts` files automatically.

### 7. Bundle for Production

```bash
bun build ./src/index.ts --outdir ./dist --minify
```

Outputs optimized bundle to `dist/`. Use `--target browser|node|bun` to control output format.

### 8. Create Standalone Executable

```bash
bun build ./cli.ts --outfile mycli --compile
./mycli
```

Bundles code + Bun runtime into single executable; no dependencies needed.

## Common Gotchas

- **Lifecycle scripts disabled by default**: Bun doesn't run `postinstall` scripts for security. Add trusted packages to `trustedDependencies` in `package.json` to allow them.
- **`bun run` vs `bun <script>`**: If a built-in Bun command exists with the same name, use `bun run <script>` explicitly to run package.json scripts.
- **Watch mode flag placement**: Use `bun --watch run file.ts`, not `bun run file.ts --watch`. Flags after the filename are passed to the script itself.
- **TypeScript errors on Bun global**: Install `@types/bun` and add `"lib": ["ESNext"]` to `tsconfig.json` compilerOptions.
- **Lockfile format**: Bun v1.2+ uses text `bun.lock` by default (not binary `bun.lockb`). Commit to version control.
- **Auto-install disabled in CI**: Set `install.auto = "disable"` in `bunfig.toml` for production to prevent unexpected package downloads.
- **Node.js compatibility**: Bun implements most Node.js APIs but not all. Check docs for `node:` module support before relying on Node-specific code.
- **Bundler always bundles**: Unlike esbuild, `bun build` always bundles by default. Use `Bun.Transpiler` to transpile individual files without bundling.
- **No type checking in bundler**: `bun build` does not type-check. Run `tsc --noEmit` separately for type validation.
- **Peer dependencies installed by default**: Unlike npm, Bun installs peer dependencies automatically. Set `peer = false` in `bunfig.toml` to disable.

## Verification Checklist

Before submitting work with Bun:

- [ ] Run `bun install` to verify dependencies resolve without errors
- [ ] Run `bun run <script>` to test main entry point
- [ ] Run `bun test` and verify all tests pass
- [ ] Run `bun build` and check output files exist in `outdir`
- [ ] Verify `bun.lock` is committed to version control (not `.gitignore`d)
- [ ] Check `bunfig.toml` for any environment-specific settings that should be removed
- [ ] Confirm no `node_modules` folder is committed (should be in `.gitignore`)
- [ ] Test with `--production` flag if building for deployment: `bun install --production`
- [ ] Verify TypeScript files have no type errors: `bun run tsc --noEmit` (if tsc installed)
- [ ] Check that `package.json` `"type": "module"` is set for ESM projects

## Resources

**Comprehensive navigation**: https://bun.com/docs/llms.txt — Page-by-page listing of all Bun documentation.

**Critical pages**:

1. [Bun Runtime](https://bun.com/docs/runtime) — Execute files, scripts, and manage the runtime
2. [Package Manager](https://bun.com/docs/pm/cli/install) — Install, add, remove packages and manage dependencies
3. [Bundler](https://bun.com/docs/bundler) — Bundle JavaScript/TypeScript for production
4. [Test Runner](https://bun.com/docs/test) — Write and run Jest-compatible tests
5. [bunfig.toml](https://bun.com/docs/runtime/bunfig) — Configure Bun's behavior

---

> For additional documentation and navigation, see: https://bun.com/docs/llms.txt
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
bun

Directory Structure

SKILL.md

Report

Notice
