Bun Commands Cheat Sheet

What is Bun?

Bun is an all-in-one JavaScript/TypeScript toolkit that includes a runtime, package manager, test runner, and bundler. It's designed to be a drop-in replacement for Node.js with significantly faster performance.

Simply its a,

Runtime: Execute JavaScript/TypeScript files with near-zero overhead

Package Manager: Install packages up to 30x faster than npm

Test Runner: Jest-compatible testing with TypeScript support

Bundler: Native bundling for JS/TS/JSX with code splitting

---

Installation

macOS & Linux

curl -fsSL https://bun.sh/install | bash

Windows (PowerShell)

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

Using npm (Works everywhere)

npm install -g bun

Docker

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

Verify Installation

bun --version

Upgrade Bun

bun upgrade

---

Project Initialization

Create a React App

# Create a new React app
bun init --react

# Run in development mode
bun dev

# Build for production
bun run build

# Run production server
bun start

Create a Next.js App

# Create a new Next.js app
bun create next-app@latest my-app

# Navigate to project
cd my-app

# Start development server with Bun runtime
bun --bun run dev

Update package.json scripts for Next.js:

{
  "scripts": {
    "dev": "bun --bun next dev",
    "build": "bun --bun next build",
    "start": "bun --bun next start"
  }
}

Create Other Projects

# Create from a GitHub template
bun create <user>/<repo> <destination>

# Examples
bun create elysia my-elysia-app
bun create hono my-hono-app

---

Package Management

Install Dependencies

# Install all dependencies from package.json
bun install

# Install with verbose logging
bun install --verbose

# Install silently (no output)
bun install --silent

# Production install (no devDependencies)
bun install --production

Add Packages

# Add a dependency
bun add <package>

# Add specific version
bun add react@18.2.0

# Add latest version
bun add react@latest

# Add as dev dependency
bun add -d <package>
bun add --dev typescript

# Add as exact version (no ^ prefix)
bun add zod --exact

Remove Packages

bun remove <package>

Update Packages

# Check for outdated packages
bun outdated

# Update all packages
bun update

Common Package Examples

# React ecosystem
bun add react react-dom
bun add -d @types/react @types/react-dom

# Next.js
bun add next

# Tailwind CSS
bun add -d tailwindcss postcss autoprefixer
bunx tailwindcss init -p

# TypeScript
bun add -d typescript @types/node

# Testing libraries
bun add -d @testing-library/react jest

# Popular utilities
bun add zod axios lodash

---

Running Scripts

Run Files

# Run a JavaScript/TypeScript file
bun run index.ts
bun run index.js
bun run index.tsx

# Shorthand (without 'run')
bun index.ts

Run package.json Scripts

# Run a script from package.json
bun run dev
bun run build
bun run start

# Run with Bun runtime (instead of Node)
bun --bun run dev

Watch Mode

# Run with auto-reload on file changes
bun --watch run index.ts

Execute Packages (bunx)

# Execute a package without installing globally
bunx cowsay "Hello, Bun!"

# Create React App alternative
bunx create-react-app my-app

# Run Tailwind CLI
bunx tailwindcss -i ./src/input.css -o ./dist/output.css

---

Testing

Run Tests

# Run all tests
bun test

# Run specific test file
bun test ./test/specific-file.test.ts

# Run tests matching a pattern
bun test --test-name-pattern "addition"

# Watch mode
bun test --watch

Test File Naming

Bun automatically detects test files with these patterns:

*.test.{js|jsx|ts|tsx}

*_test.{js|jsx|ts|tsx}

*.spec.{js|jsx|ts|tsx}

*_spec.{js|jsx|ts|tsx}

Writing Tests

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

describe("math operations", () => {
  test("2 + 2 equals 4", () => {
    expect(2 + 2).toBe(4);
  });

  test("arrays match", () => {
    expect([1, 2, 3]).toEqual([1, 2, 3]);
  });
});

---

Bundling

Basic Bundle

# Bundle for browser
bun build ./index.tsx --outdir ./out

# Bundle with minification
bun build ./index.tsx --outdir ./out --minify

# Watch mode
bun build ./index.tsx --outdir ./out --watch

Bundle Options

# Bundle for different targets
bun build ./index.ts --target browser
bun build ./index.ts --target bun
bun build ./index.ts --target node

# Generate source maps
bun build ./index.tsx --outdir ./out --sourcemap

# Code splitting
bun build ./index.tsx --outdir ./out --splitting

---

Plugins

Bun supports plugins for extending bundler functionality. Plugins can be configured in bunfig.toml.

TailwindCSS Plugin

Bun has a built-in TailwindCSS plugin for seamless integration:

# Install TailwindCSS and the Bun plugin
bun add tailwindcss bun-plugin-tailwind

Configure in bunfig.toml:

[serve.static]
plugins = ["bun-plugin-tailwind"]

Use in HTML (add to head):

Add this link tag to your HTML head section

<link rel="stylesheet" href="tailwindcss" />

Or import in CSS:

@import "tailwindcss";

.custom-class {
  @apply bg-red-500 text-white;
}

Custom Plugins

You can create custom plugins by implementing the BunPlugin interface:

# bunfig.toml
[serve.static]
plugins = ["./my-plugin.ts"]

// my-plugin.ts
import type { BunPlugin } from "bun";

const myPlugin: BunPlugin = {
  name: "my-custom-plugin",
  setup(build) {
    build.onLoad({ filter: /\.custom$/ }, async (args) => {
      const text = await Bun.file(args.path).text();
      return {
        contents: "export default " + JSON.stringify(text) + ";",
        loader: "js",
      };
    });
  },
};

export default myPlugin;

---

Environment Variables

# Bun automatically loads .env files
# Create .env file and access via process.env or Bun.env

# Access in code
console.log(Bun.env.MY_VARIABLE);
console.log(process.env.MY_VARIABLE);

Quick Commands Reference