Getting started with Bun: runtime, package manager, and scripts

Bun is an all-in-one toolkit for JavaScript and TypeScript: it is a runtime (like Node.js), a package manager, a bundler, and a test runner. It is built for speed and aims to be a drop-in replacement for Node.js in many workflows.

What Bun provides

Installation

macOS and Linux

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

Windows

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

Other methods

# npm (if you have Node.js)
npm install -g bun

# Homebrew
brew install oven-sh/bun/bun

# Docker
docker pull oven/bun

Verify installation:

bun --version

Running scripts

Single file

bun run index.js
bun index.ts       # TypeScript works directly
bun app.tsx        # JSX works too

Watch mode

bun --watch index.ts

Package scripts

bun run dev        # Runs "dev" script from package.json
bun run build
bun run test

Package management

Install dependencies

bun install        # Install from package.json
bun i              # Shorthand

Add packages

bun add react
bun add -D typescript @types/react  # Dev dependency
bun add -g serve                     # Global

Remove packages

bun remove lodash

Lockfile

Bun generates bun.lockb (binary lockfile) for faster installs. It also reads package-lock.json if present.

Creating a project

bun init my-project
cd my-project

This creates:

• package.json
• index.ts
• tsconfig.json
• .gitignore

Built-in APIs

Bun includes optimized built-in APIs:

File system

// Read file
const file = Bun.file('config.json');
const content = await file.text();
const json = await file.json();

// Write file
await Bun.write('output.txt', 'Hello, Bun!');

HTTP server

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

console.log('Server running at http://localhost:3000');

Environment variables

// Automatic .env loading
const apiKey = Bun.env.API_KEY;
const dbUrl = process.env.DATABASE_URL; // Node.js compat

Testing with Bun

Write tests

// math.test.ts
import { expect, test, describe } from 'bun:test';

describe('math', () => {
  test('addition', () => {
    expect(1 + 1).toBe(2);
  });

  test('async', async () => {
    const result = await Promise.resolve(42);
    expect(result).toBe(42);
  });
});

Run tests

bun test              # Run all tests
bun test math.test.ts # Run specific file
bun test --watch      # Watch mode

Bundling

# Bundle for production
bun build ./src/index.ts --outdir ./dist

# With options
bun build ./src/index.ts \
  --outdir ./dist \
  --minify \
  --sourcemap \
  --target browser

Bun vs Node.js

Compatibility

Bun implements most Node.js APIs:

Most npm packages work. Test packages with native dependencies or obscure Node.js APIs.

When to use Bun

Good fit

• New projects wanting fast tooling
• Scripts and CLI tools
• Development workflows
• Projects that benefit from fast installs
• TypeScript projects (no compile step)

Consider alternatives

• Production apps with specific Node.js requirements
• Heavy use of native modules
• Need guaranteed compatibility
• Deployment platforms without Bun support

Example project structure

my-bun-app/
  src/
    index.ts
    routes/
    utils/
  tests/
    index.test.ts
  package.json
  tsconfig.json
  bunfig.toml        # Optional Bun config

bunfig.toml (optional)

[install]
registry = "https://registry.npmjs.org/"

[test]
coverage = true

Summary

Bun provides:

1. Fast runtime with JavaScriptCore
2. Native TypeScript without build step
3. Built-in package manager faster than npm
4. Built-in test runner with Jest compatibility
5. Built-in bundler for production builds

The Bun documentation has complete API references and guides.