Bun Package Manager Expert

Bun Package Manager Expert

Purpose

Expert knowledge of Bun's package manager. Covers dependency installation, workspaces/​monorepos, lockfile management, and npm/​yarn/​pnpm migration. 25x faster than npm, 6x faster than pnpm.

When to Use

Invoke this skill when:

• Installing packages (bun install, bun add)
• Managing workspaces/​monorepos
• Configuring package manager settings
• Troubleshooting lockfile issues (bun.lockb)
• Migrating from npm, yarn, or pnpm
• Setting up private registries
• Managing global packages
• Optimizing install performance

Documentation Available

Location: /​Users/​zach/​Documents/​cc-skills/​docs/​bun/​install/

Coverage (23 files):

• Package installation commands
• Workspaces and monorepos
• Lock file (bun.lockb binary format)
• Package.json configuration
• npmrc and registry configuration
• Dependency overrides and patches
• Global cache management
• Lifecycle scripts
• Trusted dependencies

Related Skills

• bun-runtime: For running installed packages
• bun-test: For installing test dependencies
• bun-bundler: For bundling with dependencies

Best Practices

• Use bun.lockb - Binary lockfile is 10x smaller and faster
• Enable workspaces - For monorepo management
• Use --production - Skip devDependencies in production
• Leverage global cache - Shared across projects
• Pin versions - Use exact versions in package.json
• Use bun update --latest - Update to latest versions safely
• Configure registry - For private packages

Examples

Example 1: Basic Package Management

Question: "How do I install and manage packages?"

Response:

# Install all dependencies from package.json
bun install

# Add a package
bun add react

# Add dev dependency
bun add --dev typescript

# Add specific version
bun add [email protected]

# Add global package
bun add --global typescript

# Remove package
bun remove react

# Update all packages
bun update

# Update to latest (ignoring semver)
bun update --latest

# Install from specific registry
bun install --registry https://registry.example.com

Performance: Bun install is 25x faster than npm!

References:

• See: docs/​bun/​install/​install.md
• See: docs/​bun/​install/​add.md

Example 2: Workspaces (Monorepo)

Question: "How do I set up a monorepo with workspaces?"

Response:

Project structure:

my-monorepo/
├── package.json
├── packages/
│   ├── app/
│   │   └── package.json
│   ├── ui/
│   │   └── package.json
│   └── utils/
│       └── package.json

Root package.json:

{
  "name": "my-monorepo",
  "workspaces": ["packages/​*"]
}

packages/​app/​package.json:

{
  "name": "@myorg/​app",
  "dependencies": {
    "@myorg/​ui": "workspace:*",
    "@myorg/​utils": "workspace:*",
    "react": "^18.2.0"
  }
}

Install all workspace dependencies:

bun install

Run commands in workspace:

# Run in specific workspace
bun --filter @myorg/​app run dev

# Run in all workspaces
bun --filter '*' run build

# Install in specific workspace
bun --filter @myorg/​app add lodash

References:

• See: docs/​bun/​install/​workspaces.md

Example 3: Lockfile Management

Question: "What is bun.lockb and how do I use it?"

Response:

bun.lockb is Bun's binary lockfile:

• 10x smaller than package-lock.json
• Faster to read/​write
• Git-friendly (designed for version control)
• Deterministic installs

Lockfile operations:

# Generate lockfile
bun install

# Update lockfile
bun install --force

# Print lockfile (human-readable)
bun install --dry-run

# Ignore lockfile (not recommended)
bun install --no-save

# Check lockfile integrity
bun pm ls

Commit lockfile to version control:

git add bun.lockb
git commit -m "Update dependencies"

References:

• See: docs/​bun/​install/​lockfile.md

Example 4: Private Registry

Question: "How do I use a private npm registry?"

Response:

Method 1: .npmrc file

# .npmrc
registry=https://registry.example.com
//registry.example.com/:_authToken=${NPM_TOKEN}

Method 2: bunfig.toml

# bunfig.toml
[install]
registry = "https://registry.example.com"

[install.registry]
url = "https://registry.example.com"
token = "${NPM_TOKEN}"

Method 3: Command line

bun install --registry https://registry.example.com

Scoped packages:

# .npmrc
@myorg:registry=https://registry.example.com

References:

• See: docs/​bun/​install/​registry.md

Example 5: Dependency Overrides

Question: "How do I override a transitive dependency?"

Response:

Using overrides in package.json:

{
  "name": "my-app",
  "dependencies": {
    "some-package": "^1.0.0"
  },
  "overrides": {
    "vulnerable-dep": "2.0.0"
  }
}

Using resolutions (Yarn compat):

{
  "name": "my-app",
  "resolutions": {
    "lodash": "4.17.21"
  }
}

Install with overrides:

bun install

References:

• See: docs/​bun/​install/​overrides.md

Configuration

bunfig.toml

# bunfig.toml
[install]
# Production mode (skip devDependencies)
production = false

# Peer dependencies behavior
peer = true

# Concurrent download limit
concurrent = 10

# Registry configuration
registry = "https://registry.npmjs.org"

# Cache directory
cache = "~/​.bun/​install/​cache"

# Lockfile path
lockfile = "bun.lockb"

# Frozen lockfile (CI mode)
frozenLockfile = false

Global Cache

Bun uses a global cache shared across all projects:

# Cache location
~/​.bun/​install/​cache

# Clear cache
rm -rf ~/​.bun/​install/​cache

# View cache size
du -sh ~/​.bun/​install/​cache

Benefits:

• Faster installs - Reuse already downloaded packages
• Save disk space - No duplication across projects
• Offline installs - Work without network

Lifecycle Scripts

Bun runs npm lifecycle scripts automatically:

{
  "scripts": {
    "preinstall": "echo 'Before install'",
    "install": "echo 'During install'",
    "postinstall": "echo 'After install'",
    "prepare": "echo 'Before publish'"
  }
}

Run scripts:

bun run build       # Run custom script
bun run test        # Run test script
bun install         # Runs pre/​post install scripts

Migration from npm/​yarn

From npm:

# Remove npm artifacts
rm -rf node_modules package-lock.json

# Install with Bun
bun install

# Commit new lockfile
git add bun.lockb

From yarn:

# Remove yarn artifacts
rm -rf node_modules yarn.lock

# Install with Bun
bun install

# Workspaces work the same!

Compatibility:

• ✅ package.json (100% compatible)
• ✅ Workspaces (compatible with npm/​yarn/​pnpm)
• ✅ .npmrc (fully supported)
• ✅ Lifecycle scripts
• ⚠️ Lockfile format different (bun.lockb vs package-lock.json)

Search Helpers

# Find install docs
grep -r "install\|add\|remove" docs/​bun/​install/

# Find workspace docs
grep -r "workspace\|monorepo" docs/​bun/​install/

# Find lockfile docs
grep -r "lockfile\|bun.lockb" docs/​bun/​install/

# List all package manager docs
ls docs/​bun/​install/

Common Issues

• Lockfile conflicts: Different Bun versions generated lockfile

  • Solution: Update Bun, regenerate with bun install --force

• Peer dependency warnings: Package requires peer deps

  • Solution: Install peer dependencies or use --ignore-peer-dependencies

• Private registry auth: 401 Unauthorized

  • Solution: Check .npmrc, verify token

• Slow installs: Network issues or registry problems

  • Solution: Check network, try different registry

Performance Benchmarks

Bun is 25x faster than npm!

Notes

• Documentation covers latest Bun version
• bun.lockb is a binary format (not human-readable)
• Bun caches packages globally (~/​.bun/​install/​cache)
• File paths reference local documentation cache
• For latest updates, check https://bun.sh/docs/cli/install