bun-package-manager

Bun Package Manager

When to Use This Skill

Scenario	Use this skill	Alternative
Installing all project dependencies	Yes	N/A
Adding or removing packages	Yes	bun-add for quick single-package additions
Updating packages or checking outdated	Yes	N/A
Managing workspace dependencies	Yes	N/A
CI reproducible installs (--frozen-lockfile)	Yes	N/A
Running scripts or tests	No - use bun-development	bun-test for quick test runs
Publishing packages to npm	No - use bun-publishing	N/A
Debugging lockfile conflicts	Yes	bun-lockfile-update for targeted lockfile operations

Core Expertise

Bun's package manager is significantly faster than npm/yarn/pnpm:

• ~7x faster than npm
• ~4x faster than pnpm
• Native workspace support
• Compatible with npm registry

Essential Commands

Install Dependencies

# Standard install
bun install

# CI/reproducible (frozen lockfile)
bun install --frozen-lockfile

# Production only (no devDependencies)
bun install --production

# Force reinstall
bun install --force

# Dry run (preview)
bun install --dry-run

Add Packages

# Add dependency
bun add <package>

# Add dev dependency
bun add --dev <package>
bun add -d <package>

# Pin exact version (no ^)
bun add --exact <package>
bun add -E <package>

# Global install
bun add --global <package>
bun add -g <package>

# Add to specific workspace
bun add <package> --cwd packages/mylib

Remove Packages

# Remove dependency
bun remove <package>

# Remove from devDependencies
bun remove --dev <package>

# Dry run
bun remove --dry-run <package>

Update Packages

# Update within semver ranges
bun update

# Update to latest (ignore ranges)
bun update --latest

# Interactive selection
bun update --interactive

# Update across workspaces
bun update --recursive

Inspect Dependencies

# Check outdated packages
bun outdated

# Why is package installed?
bun why <package>

# List installed packages
bun pm ls

# View package cache
bun pm cache

Workspace Management

Configuration

{
  "name": "monorepo",
  "private": true,
  "workspaces": ["packages/*", "apps/*"]
}

Workspace Operations

# Install all workspace deps
bun install

# Add to specific workspace
bun add express --cwd apps/api

# Run in matching workspaces
bun run --filter 'package-*' build

# Run in all workspaces
bun run --workspaces test

Inter-workspace Dependencies

{
  "dependencies": {
    "shared-utils": "workspace:*"
  }
}

Agentic Optimizations

Context	Command
CI install	bun install --frozen-lockfile
Prod deploy	bun install --production
Preview changes	bun add --dry-run <pkg>
Exact versions	bun add --exact <pkg>
Workspace target	bun add <pkg> --cwd <path>
Force refresh	bun install --force

Quick Reference

Flag	Short	Description
--frozen-lockfile		Fail if lockfile changes
--production	-p	Skip devDependencies
--dev	-d	Add to devDependencies
--exact	-E	Pin exact version
--global	-g	Global install
--dry-run		Preview without executing
--force	-f	Force reinstall all
--cwd <path>		Target directory
--latest		Update to latest version
--recursive		Apply across workspaces

Error Handling

Common Issues

Lockfile mismatch in CI:

# Use frozen lockfile
bun install --frozen-lockfile

Peer dependency conflicts:

# Force install anyway
bun install --force

Package not found:

# Check if package exists
bun why <package>

Environment Variables

Variable	Description
BUN_OPTIONS	Global CLI flags
BUN_INSTALL	Bun installation directory