bun

---
name: bun
description: >-
  Assists with using Bun as an all-in-one JavaScript/TypeScript runtime, package manager, bundler,
  and test runner. Use when building HTTP servers, managing packages, running tests, or migrating
  from Node.js. Trigger words: bun, bun serve, bun install, bun test, bun build, javascript
  runtime, bun runtime.
license: Apache-2.0
compatibility: "Requires Bun installed (macOS, Linux, WSL)"
metadata:
  author: terminal-skills
  version: "1.0.0"
  category: development
  tags: ["bun", "javascript-runtime", "package-manager", "bundler", "typescript"]
---

# Bun

## Overview

Bun is an all-in-one JavaScript/TypeScript runtime that replaces Node.js, npm, webpack, and Jest with a single binary. It provides native TypeScript support, a high-performance HTTP server (`Bun.serve()`), a fast package manager, a bundler, and a Jest-compatible test runner with dramatically faster performance.

## Instructions

- When creating HTTP servers, use `Bun.serve()` which handles 100K+ req/s with built-in WebSocket support, TLS, and streaming responses.
- When managing packages, use `bun install` (10-30x faster than npm), `bun add`, `bun remove`, and prefer `bun.lock` (text format) for readable git diffs.
- When bundling, use `Bun.build()` with appropriate target (`"browser"`, `"bun"`, `"node"`), enable code splitting with `splitting: true`, and configure tree shaking.
- When writing tests, use `bun test` with Jest-compatible API (`describe`, `it`, `expect`), snapshot testing, mocking with `mock.module()`, and `--coverage` for code coverage.
- When doing file I/O, prefer `Bun.file()` and `Bun.write()` over Node.js `fs` for significantly faster file operations, and use `Bun.Glob` for pattern matching.
- When handling authentication, use `Bun.password.hash()` and `Bun.password.verify()` for bcrypt/argon2 instead of npm packages.
- When migrating from Node.js, replace `node` with `bun` in scripts, keep `package.json` unchanged, and note that most npm packages work without modifications. Use `bun:sqlite` for embedded databases instead of SQLite npm packages.

## Examples

### Example 1: Build a high-performance API server

**User request:** "Create a REST API using Bun's built-in HTTP server"

**Actions:**
1. Create server with `Bun.serve()` and route handler
2. Parse JSON bodies with `request.json()` and return `Response` objects
3. Add WebSocket upgrade for real-time features
4. Use `Bun.password` for auth and `bun:sqlite` for data storage

**Output:** A fast API server using only Bun built-ins with no external dependencies.

### Example 2: Migrate a Node.js project to Bun

**User request:** "Switch my Express project from Node.js to Bun"

**Actions:**
1. Replace `npm install` with `bun install` in CI and local setup
2. Update `package.json` scripts to use `bun run` instead of `node`
3. Replace `dotenv` with Bun's built-in `.env` loading
4. Switch test runner from Jest to `bun test` with same test files

**Output:** A Bun-powered project with faster installs, startup, and test execution.

## Guidelines

- Use `Bun.serve()` for new HTTP servers; it is significantly faster than Express on Bun.
- Prefer `Bun.file()` and `Bun.write()` over Node.js `fs` for file operations.
- Use `bun:sqlite` for local data instead of adding SQLite npm packages.
- Use `Bun.password` for auth instead of `bcrypt`/`argon2` npm packages for zero native dependencies.
- Keep `bun.lock` (text format) in git for readable diffs.
- Test with `bun test` instead of Jest for the same API with dramatically faster execution.
- When targeting browsers, use `Bun.build()` with `target: "browser"`.