Set Up Bun Development Environment - Actually Fast JavaScript Tooling

Look, Bun is JavaScript tooling that doesn't make you want to punch your monitor. It's a runtime like Node.js but built on JavaScriptCore instead of V8. What does that mean for you? Your apps start faster and your package installs don't take longer than a coffee break. The official Bun blog has detailed performance comparisons, and Stack Overflow discussions show real developer experiences.

I've been testing Bun since it hit 1.0 stability, and the latest 1.2.21 (dropped just last week) is the most solid yet. Honestly, the speed difference is addictive. Going back to npm feels like watching paint dry. When I first tried bun install on a typical React project, it finished installing 200+ packages in like 2-5 seconds. npm would have taken 30-60 seconds on the same machine - sometimes way longer if your luck's bad.

The Reality of Bun's "All-in-One" Approach

Bun tries to replace your entire JavaScript toolchain:

• Runtime: Runs JS/TS/JSX without separate transpilation. Works great until you hit weird edge cases with some experimental TS features. See Bun's TypeScript documentation for current support details.
• Package Manager: Fast as hell, but npm audit doesn't work, so security scanning needs alternative tools like Snyk or OSSF Scorecard.
• Bundler: Built-in but less configurable than webpack. Fine for simple projects, pain in the ass for complex builds. Check Bun's bundler docs for limitations.
• Test Runner: Jest-compatible and legitimately fast. I've seen test suites that took 45 seconds with Jest run in 8 seconds with Bun. See Bun test documentation for API differences.
• Web Server: Bun.serve() is surprisingly solid for APIs. Handles thousands of concurrent connections without breaking a sweat. Fastify and Express both work with Bun.

The Node.js Compatibility Lie

Bun claims "100% Node.js compatibility" which is complete bullshit. It works with most Node.js stuff, but I've hit weird edge cases:

• Native modules can be a nightmare - some just refuse to compile
• Certain npm scripts break because they assume npm's behavior
• Path resolution sometimes gets confused with complex monorepo setups
• The crypto module has subtle differences that can bite you

Pro tip: Test your specific dependencies before committing to Bun in production. I learned this the hard way when a critical auth library failed during deployment - turns out it relied on some obscure Node.js internal that Bun doesn't implement. Spent 4 hours at 2am rolling back to Node.js because our users couldn't log in.

Other fun gotchas I've encountered:

• Windows PATH gets fucked up if you have spaces in your username
• The install script breaks on corporate networks with SSL inspection
• Some Docker base images don't have the right libc version and Bun just crashes with cryptic errors
• Hot reload randomly stops working and you have to restart the dev server (classic JavaScript tooling)

When Bun Actually Makes Sense

Despite the gotchas, Bun shines in these scenarios:

• New projects: Start fresh without legacy baggage
• CI/CD pipelines: Faster installs = shorter build times
• Development tools: CLIs and scripts benefit from quick startup
• API servers: Performance is legitimately impressive - 20-50% more requests per second than Node.js in my testing

The setup process I'm about to walk you through covers installation across platforms, handling the gotchas I've discovered, and getting a real project running without the usual JavaScript tooling hell.

My take after 2+ years with Bun: It's not perfect, but it's genuinely faster for development and the ecosystem compatibility is good enough for most projects. I'd start new projects with Bun today - just test your critical dependencies first and keep Node.js as a backup plan.

The Easy Way (macOS/Linux)

Just run this and pray to the JavaScript gods:

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

This drops Bun into ~/.bun/bin/ and tries to add it to your PATH. Usually works fine, but on some Linux distros you need to manually source your shell config or the PATH doesn't update. The official installation guide covers all platforms, and GitHub issues show common problems. If bun --version gives you "command not found" after installation, restart your terminal or run:

## On bash
source ~/.bashrc

## On zsh (most modern macOS)
source ~/.zshrc

macOS with Homebrew (My Preferred Method):

brew install bun

Homebrew handles the PATH nonsense for you and makes updates easier with brew upgrade bun. Check the Homebrew formula for version info.

Ubuntu/Debian Gotcha:
Some minimal Docker images don't have unzip which the installer needs:

sudo apt install unzip curl -y
curl -fsSL https://bun.sh/install | bash

Windows (Good Luck)

Windows support exists but it's... Windows:

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

Honestly though, if you're doing serious development on Windows, just use WSL2. The native Windows version has path handling issues and weird compatibility problems with some npm packages. See Windows development guides for setup help, and Bun's Windows documentation for known limitations.

Docker (When You Need Consistent Builds)

Here's a working Dockerfile that won't make you hate containerization:

FROM oven/bun:1.2.21-alpine
WORKDIR /app

## Copy package files first for better layer caching
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile

## Copy source code
COPY . .
EXPOSE 3000
CMD [\"bun\", \"run\", \"start\"]

Alpine vs Ubuntu Base Images:

• oven/bun:1.2.21-alpine: Smaller (50MB vs 200MB) but some native modules break. See Alpine Linux docs and Docker Hub tags for options.
• oven/bun:1.2.21: Larger but better compatibility with weird npm packages. Check Debian base image info for security updates.

Testing Your Installation

Run this and make sure you get a version number:

bun --version

If it says something like 1.2.21, you're golden. If you get "command not found", the PATH didn't update - see the shell sourcing commands above.

Quick Sanity Check:

bun --help
echo \"console.log('Hello from Bun')\" | bun -

The second command should print "Hello from Bun" immediately. If it hangs or errors, something's fucked with your installation.

Common Installation Failures I've Seen

• Corporate firewalls: The install script gets blocked. Download the binary manually from GitHub releases
• Old Node.js versions: Bun doesn't care about your Node.js version, but some post-install scripts do
• Missing libc: On some minimal Linux containers, you need apk add gcompat (Alpine) or equivalent
• M1/M2 Mac ARM issues: Usually fine now, but older versions had platform detection problems

Getting Started (The Right Way)

Skip the bullshit tutorials and just create a project:

mkdir my-app && cd my-app
bun init -y  # Skip the interactive prompts

bun init creates the basic files, but here's what actually matters:

• index.ts - Your main file (yes, TypeScript by default because Bun isn't stuck in 2015)
• package.json - Same as Node.js, Bun doesn't reinvent everything
• bun.lockb - Bun's lockfile format (binary, much faster than npm's giant JSON)

Pro tip: The generated tsconfig.json has decent defaults but you'll want to tweak it. The default "target": "ES2017" works fine unless you're supporting Internet Explorer (please don't).

Project Structure That Won't Make You Hate Life

Stop overthinking it and use this:

my-app/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # If you're building an API
│   └── lib/              # Reusable code
├── tests/
│   └── *.test.ts         # Bun runs anything ending in .test.ts
├── package.json
└── bun.lockb             # Don't commit this to git unless you want merge conflicts

Real Talk: Don't create a dist/ folder until you actually need it. Bun runs TypeScript directly so you might never need a build step.

Commands That Actually Work

Running stuff:

bun run src/index.ts      # Basic execution
bun --hot src/index.ts    # Hot reload (actually works unlike nodemon)

The --hot flag is legitimately good. It watches files and restarts your app when they change. I've never seen it get confused with circular imports like some other solutions.

Installing packages (the fun part):

bun add express           # Add a package (stupid fast)
bun add -d @types/express # Dev dependencies
bun install              # Restore from lockfile

Testing (where Bun shines):

bun test                 # Run all tests
bun test --watch         # Watch mode that doesn't suck
bun test user.test.ts    # Run specific file

Bun's test runner is Jest-compatible but way faster. I've seen test suites go from 45 seconds (Jest) to 6 seconds (Bun test). Check the test API documentation and migration guide from Jest for differences.

The bunfig.toml File (Actually Useful)

Most tutorials skip this but it's handy for team consistency. The bunfig.toml documentation covers all options, and TOML syntax guide helps with formatting:

[install]
## Don't install optional dependencies (speeds up CI)
optional = false
## Use exact versions (prevents \"works on my machine\")
exact = true

[run]
## Use bash for scripts (some npm scripts assume bash)
shell = \"/bin/bash\"

[test]
## Longer timeout for slow integration tests
timeout = 30000

Warning: The exact = true setting can break some packages that expect semver ranges. Start with false and only enable if you have version hell problems.

Hot Reload Reality Check

The --hot flag works great until:

• You have circular imports (it gets confused)
• You're importing JSON files (sometimes doesn't detect changes)
• You're running in Docker (file watching can be flaky)

If hot reload stops working, kill the process and restart. That fixes it 90% of the time.

What Actually Breaks

After using Bun for real projects, here's what to watch out for:

• Some native modules won't compile - sharp, bcrypt, and others need specific versions
• npm scripts that use shell features - they assume npm's script runner behavior
• Path resolution with monorepos - can get confused with complex workspace setups
• File watching in containers - use --poll flag if --hot doesn't work in Docker

Bottom line: Start simple. A single TypeScript file with bun run will probably just work. Add complexity only when you need it.