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 react@18.2.0

# 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

Operation	npm	yarn	pnpm	Bun
Cold install	30s	20s	15s	1.2s
Warm install	20s	12s	8s	0.5s
With lockfile	15s	10s	6s	0.3s

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