/bun

name: bun
description: Build fast applications with Bun JavaScript runtime. Use when creating Bun projects, using Bun APIs, bundling, testing, or optimizing Node.js alternatives. Triggers on Bun, Bun runtime, bun.sh, bunx, Bun serve, Bun test, JavaScript runtime.

Bun - The Fast JavaScript Runtime

Build and run JavaScript/TypeScript applications with Bun's all-in-one toolkit.

Quick Start

# Install Bun (macOS, Linux, WSL)
curl -fsSL https://bun.sh/install | bash

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

# Create new project
bun init

# Run TypeScript directly (no build step!)
bun run index.ts

# Install packages (faster than npm)
bun install

# Run scripts
bun run dev

Package Management

# Install dependencies
bun install              # Install all from package.json
bun add express          # Add dependency
bun add -d typescript    # Add dev dependency
bun add -g serve         # Add global package

# Remove packages
bun remove express

# Update packages
bun update

# Run package binaries
bunx prisma generate     # Like npx but faster
bunx create-next-app

# Lockfile
bun install --frozen-lockfile  # CI mode

bun.lockb vs package-lock.json

# Bun uses binary lockfile (bun.lockb) - much faster
# To generate yarn.lock for compatibility:
bun install --yarn

# Import from other lockfiles
bun install  # Auto-detects package-lock.json, yarn.lock

Bun Runtime

Run Files

# Run any file
bun run index.ts         # TypeScript
bun run index.js         # JavaScript
bun run index.jsx        # JSX

# Watch mode
bun --watch run index.ts

# Hot reload
bun --hot run server.ts

Built-in APIs

// File I/O (super fast)
const file = Bun.file('data.json');
const content = await file.text();
const json = await file.json();
const bytes = await file.arrayBuffer();

// Write files
await Bun.write('output.txt', 'Hello, Bun!');
await Bun.write('data.json', JSON.stringify({ key: 'value' }));
await Bun.write('image.png', await fetch('https://example.com/img.png'));

// File metadata
const file = Bun.file('data.json');
console.log(file.size);       // bytes
console.log(file.type);       // MIME type
console.log(file.lastModified);

// Glob files
const glob = new Bun.Glob('**/*.ts');
for await (const file of glob.scan('.')) {
  console.log(file);
}

HTTP Server

// Simple server
const server = Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);
    
    if (url.pathname === '/') {
      return new Response('Hello, Bun!');
    }
    
    if (url.pathname === '/json') {
      return Response.json({ message: 'Hello!' });
    }
    
    return new Response('Not Found', { status: 404 });
  },
});

console.log(`Server running at http://localhost:${server.port}`);

Advanced Server

Bun.serve({
  port: 3000,
  
  // Main request handler
  async fetch(req, server) {
    const url = new URL(req.url);
    
    // WebSocket upgrade
    if (url.pathname === '/ws') {
      const upgraded = server.upgrade(req, {
        data: { userId: '123' },  // Attach data to socket
      });
      if (upgraded) return undefined;
    }
    
    // Static files
    if (url.pathname.startsWith('/static/')) {
      const filePath = `./public${url.pathname}`;
      const file = Bun.file(filePath);
      if (await file.exists()) {
        return new Response(file);
      }
    }
    
    // JSON API
    if (url.pathname === '/api/data' && req.method === 'POST') {
      const body = await req.json();
      return Response.json({ received: body });
    }
    
    return new Response('Not Found', { status: 404 });
  },
  
  // WebSocket handlers
  websocket: {
    open(ws) {
      console.log('Client connected:', ws.data.userId);
      ws.subscribe('chat');  // Pub/sub
    },
    message(ws, message) {
      // Broadcast to all subscribers
      ws.publish('chat', message);
    },
    close(ws) {
      console.log('Client disconnected');
    },
  },
  
  // Error handling
  error(error) {
    return new Response(`Error: ${error.message}`, { status: 500 });
  },
});

WebSocket Client

const ws = new WebSocket('ws://localhost:3000/ws');

ws.onopen = () => {
  ws.send('Hello, server!');
};

ws.onmessage = (event) => {
  console.log('Received:', event.data);
};

Bun APIs

SQLite (Built-in)

import { Database } from 'bun:sqlite';

const db = new Database('mydb.sqlite');

// Create table
db.run(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE
  )
`);

// Insert
const insert = db.prepare('INSERT INTO users (name, email) VALUES (?, ?)');
insert.run('Alice', 'alice@example.com');

// Query
const query = db.prepare('SELECT * FROM users WHERE id = ?');
const user = query.get(1);

// All results
const allUsers = db.prepare('SELECT * FROM users').all();

// Transaction
const insertMany = db.transaction((users) => {
  for (const user of users) {
    insert.run(user.name, user.email);
  }
});

insertMany([
  { name: 'Bob', email: 'bob@example.com' },
  { name: 'Charlie', email: 'charlie@example.com' },
]);

Password Hashing (Built-in)

// Hash password
const hash = await Bun.password.hash('mypassword', {
  algorithm: 'argon2id',  // or 'bcrypt'
  memoryCost: 65536,      // 64 MB
  timeCost: 2,
});

// Verify password
const isValid = await Bun.password.verify('mypassword', hash);

Spawn Processes

// Spawn process
const proc = Bun.spawn(['ls', '-la'], {
  cwd: '/home/user',
  env: { ...process.env, MY_VAR: 'value' },
  stdout: 'pipe',
});

const output = await new Response(proc.stdout).text();
console.log(output);

// Spawn sync
const result = Bun.spawnSync(['echo', 'hello']);
console.log(result.stdout.toString());

// Shell command
const { stdout } = Bun.spawn({
  cmd: ['sh', '-c', 'echo $HOME'],
  stdout: 'pipe',
});

Hashing & Cr