LLM Best Practices

How to set up Bun as a package manager

3 min read

View markdown source

Overview

Bun is a JavaScript runtime and package manager that is significantly faster than Node.js and npm for installs and script execution. Use it to replace npm, Yarn, or pnpm in projects where raw speed matters and Node.js compatibility is not a blocking constraint. This guide installs Bun, migrates a project’s lock file, and verifies that scripts and tests run correctly. See yarn-vs-pnpm for where Bun fits in the package manager landscape.

Prerequisites

  • macOS, Linux, or Windows (WSL2). Bun has experimental native Windows support.
  • A package.json-based project. Bun is compatible with npm’s registry and lock file format.
  • No native modules that require Node.js’s node-gyp compile step if targeting Bun’s runtime. (Bun as a package manager works alongside Node.js; the runtime is separate.)

Steps

1. Install Bun

# macOS and Linux
curl -fsSL https://bun.sh/install | bash
 
# Or via Homebrew
brew install oven-sh/bun/bun
 
# Verify
bun --version

The installer adds ~/.bun/bin to your PATH. Restart the shell or source the profile if bun is not found.

2. Initialize or migrate a project

For a new project:

mkdir my-app && cd my-app
bun init

bun init generates a package.json, tsconfig.json, and index.ts.

For an existing project with an npm or pnpm lock file:

# Remove the old lock file and node_modules
rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml
 
# Install with Bun; this generates bun.lockb
bun install

bun.lockb is a binary lock file. Commit it to source control for reproducible installs.

3. Run scripts

Bun executes package.json scripts with bun run. The run keyword is optional for non-ambiguous script names.

bun run build
bun run dev
bun test          # Bun's built-in test runner

Bun’s built-in test runner is Jest-compatible. Rename test files to .test.ts and use describe, it, and expect directly; no additional package is needed.

4. Configure CI

Replace npm CI commands with Bun equivalents. For GitHub Actions:

- uses: oven-sh/setup-bun@v2
  with:
    bun-version: latest
 
- run: bun install --frozen-lockfile
- run: bun run build
- run: bun test

--frozen-lockfile fails the install if bun.lockb is out of date, catching dependency drift.

5. Add Bun type definitions (TypeScript projects)

bun add -d @types/bun

This enables type-checking for Bun.serve, Bun.file, and other Bun-specific APIs when using the Bun runtime.

Verify it worked

# Confirm Bun manages the project
bun --version
ls bun.lockb                # lock file exists
 
# Install and run
bun install
bun run build               # exits 0
bun test                    # all tests pass

If bun test runs and outputs test results, Bun is managing the project correctly.

Common errors

  • bun: command not found after install: ~/.bun/bin is not on PATH. Add export PATH="$HOME/.bun/bin:$PATH" to ~/.bashrc or ~/.zshrc.
  • Native module fails to compile: some packages use Node.js node-gyp bindings that Bun does not support. If a specific package fails, run that package under Node.js and use Bun for everything else, or switch back to npm/pnpm.
  • bun.lockb conflicts in CI: bun install --frozen-lockfile will fail if package.json was updated without regenerating the lock file. Run bun install locally and commit the new bun.lockb.
  • bun test not finding test files: Bun defaults to **/*.test.{ts,tsx,js,jsx}. If test files use a different naming convention, set test.pattern in bunfig.toml.
  • Workspace packages not resolving: declare workspaces in package.json under workspaces. Bun supports npm-style workspaces.

Graph View

Backlinks