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 / 
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 
Add specific version
bun add react@18.2.0
Add latest version
bun add react@latest
Add as dev dependency
bun add -d 
bun add --dev typescript
Add as exact version (no ^ prefix)
bun add zod --exact

Remove Packages

bun remove 

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