bun init my-app
# Choose template: Blank, React, or Library
cd my-app

This creates package.json, tsconfig.json, index.ts, and .gitignore.

2. Install Dependencies

bun install
# or add specific packages
bun add react
bun add -d typescript @types/node

Bun creates bun.lock (text-based lockfile) and node_modules/.

3. Write and Run Code

# Create index.ts with TypeScript/JSX (no compilation needed)
bun run index.ts

# Or add to package.json scripts
# "scripts": { "dev": "bun run index.ts" }
bun run dev

4. Write Tests

# Create math.test.ts
import { test, expect } from "bun:test";
test("2 + 2 = 4", () => {
  expect(2 + 2).toBe(4);
});

# Run tests
bun test
bun test --watch
bun test --coverage

5. Bundle for Production

# Build for browser
bun build ./index.tsx --outdir ./dist --target browser

# Build for Node.js
bun build ./server.ts --outdir ./dist --target node --format cjs

# Build with minification
bun build ./index.ts --outdir ./dist --minify

6. Configure bunfig.toml (Optional)

[install]
linker = "isolated"

[test]
coverage = true
coverageThreshold = 0.8

[serve]
port = 3000

Common Gotchas

• Lifecycle scripts disabled by default: Bun doesn't run postinstall scripts for security. Add packages to trustedDependencies in package.json to allow them.

• Flags go after bun, not after the command: Use bun --watch run dev, not bun run dev --watch. Flags at the end are passed to the script itself.

• bun run prefers scripts over files: If both a script and file have the same name, bun run runs the script. Use bun run ./file.ts to force file execution.

• Environment variables must be literal: process.env.FOO works in bundler, but const env = process.env; env.FOO does not. Use process.env.FOO directly.

• Auto-install only works without node_modules: If node_modules exists, Bun uses it. Delete node_modules to enable auto-install from global cache.

• Bun.lock is text-based by default: Prior to v1.2, lockfiles were binary (bun.lockb). Upgrade with bun install --save-text-lockfile --frozen-lockfile --lockfile-only.

• TypeScript 6+ requires explicit types: Add "types": ["bun"] to tsconfig.json compilerOptions if using TypeScript 6 or later.

• Phantom dependencies in hoisted mode: With linker: "hoisted", packages can import undeclared dependencies. Use linker: "isolated" to prevent this.

• Test files must match patterns: Bun only discovers *.test.ts, *_test.ts, *.spec.ts, *_spec.ts. Adjust with pathIgnorePatterns in bunfig.toml.

• Bundler doesn't type-check: Use tsc --noEmit separately for type checking. Bun's bundler only transpiles.

Verification Checklist

Before submitting work with Bun:

• Dependencies installed: bun install runs without errors
• Scripts work: bun run <script> executes correctly
• Tests pass: bun test shows all tests passing
• No TypeScript errors: Run tsc --noEmit if type checking is needed
• Bundle builds: bun build completes without errors
• Environment variables set: .env file exists with required variables
• Lockfile committed: bun.lock is in version control
• No deprecated APIs: Check Bun docs for Node.js compatibility status
• Watch mode works: bun --watch run dev detects file changes
• Hot reload functional: bun --hot run server.ts updates without restart

Resources

Comprehensive navigation: https://bun.com/docs/llms.txt

Critical pages:

1. Runtime — Running files and scripts
2. Package Manager — Installing and managing dependencies
3. Test Runner — Writing and running tests
4. Bundler — Building and bundling code

For additional documentation and navigation, see: https://bun.com/docs/llms.txt