Bun Package Manager

Use this skill when managing dependencies with Bun's package manager, which is significantly faster than npm, yarn, and pnpm while maintaining compatibility.

Key Concepts

Installing Dependencies

Bun's package manager is drop-in compatible with npm:

# Install all dependencies
bun install

# Add a dependency
bun add express
bun add -d typescript  # Dev dependency
bun add -g cowsay      # Global install

# Add specific version
bun add react@18.2.0

# Install from different sources
bun add git@github.com:user/repo.git
bun add ./local-package

Removing Dependencies

# Remove a dependency
bun remove express

# Remove dev dependency
bun remove -d typescript

Updating Dependencies

# Update all dependencies
bun update

# Update specific package
bun update react

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

Running Scripts

Execute package.json scripts:

# Run a script
bun run dev
bun run build
bun run test

# Short form (if no file conflict)
bun dev
bun build
bun test

Best Practices

Use bun.lockb

Bun's binary lockfile is faster and more reliable:

# Generate lockfile
bun install

# Commit bun.lockb to version control
git add bun.lockb

Workspaces

Manage monorepos with workspaces:

// package.json
{
  "name": "my-monorepo",
  "workspaces": ["packages/*", "apps/*"]
}

# Install all workspace dependencies
bun install

# Run script in specific workspace
bun --filter my-package run build

# Run script in all workspaces
bun --filter '*' run test

Package.json Configuration

Configure Bun-specific options:

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "bun run --hot src/index.ts",
    "build": "bun build src/index.ts --outdir dist",
    "start": "bun run dist/index.js",
    "test": "bun test"
  },
  "dependencies": {
    "express": "^4.18.0"
  },
  "devDependencies": {
    "@types/express": "^4.17.0",
    "bun-types": "latest"
  },
  "peerDependencies": {
    "typescript": "^5.0.0"
  }
}

TypeScript Configuration

Set up proper TypeScript support:

// tsconfig.json
{
  "compilerOptions": {
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "ESNext",
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "noPropertyAccessFromIndexSignature": false,
    "types": ["bun-types"]
  }
}

Using Trusted Dependencies

Configure trusted dependencies for faster installs:

# Add trusted dependency
bun pm trust @prisma/client

# Install without lifecycle scripts (faster)
bun install --production --frozen-lockfile

Common Patterns

Migration from npm/yarn/pnpm

# Remove old lockfiles
rm package-lock.json yarn.lock pnpm-lock.yaml

# Install with Bun
bun install

# Update scripts (optional)
# Change "npm run" to "bun run"
# Change "npx" to "bunx"

Private Package Registry

Configure private registry:

# Set registry
bun config set registry https://registry.example.com

# Set scoped registry
bun config set @myorg:registry https://registry.example.com

# Set auth token
bun config set //registry.example.com/:_authToken YOUR_TOKEN

CI/CD Installation

Optimize for CI environments:

# Fast, frozen lockfile install
bun install --frozen-lockfile --production

# No save (don't update lockfile)
bun install --no-save

Development Workflow

# Install dependencies
bun install

# Run dev server with hot reload
bun --hot run src/index.ts

# Run tests in watch mode
bun test --watch

# Build for production
bun run build

Monorepo Scripts

// Root package.json
{
  "scripts": {
    "dev": "bun --filter '*' run dev",
    "build": "bun --filter '*' run build",
    "test": "bun --filter '*' run test",
    "lint": "bun --filter '*' run lint"
  }
}

// Package in workspace
{
  "name": "@myorg/shared",
  "scripts": {
    "dev": "bun run --hot src/index.ts",
    "build": "bun build src/index.ts --outdir dist",
    "test": "bun test"
  }
}

Link Local Packages

# In the package you want to link
bun link

# In the project using the package
bun link @myorg/my-package

# Unlink
bun unlink @myorg/my-package

Anti-Patterns

Don't Mix Package Managers

# Bad - Mixing package managers
npm install react
bun add express
yarn add vue

# Good - Use one package manager
bun add react express vue

Don't Commit node_modules

# Bad - Committing dependencies
git add node_modules

# Good - Use lockfile
git add bun.lockb
echo "node_modules" >> .gitignore

Don't Install Packages Globally Unnecessarily

# Bad - Global install for project dependency
bun add -g typescript

# Good - Install as dev dependency
bun add -d typescript

# Use bunx for one-off commands
bunx tsc --version

Don't Skip Lockfile in CI

# Bad - Updating dependencies in CI
bun install

# Good - Use frozen lockfile
bun install --frozen-lockfile

Don't Ignore Peer Dependencies

# Bad - Ignoring peer dependency warnings
bun add react-dom
# Warning: react is a peer dependency of react-dom

# Good - Install peer dependencies
bun add react react-dom

Performance Tips

Faster Installs

# Use binary lockfile
bun install  # Automatically uses bun.lockb

# Skip optional dependencies
bun install --no-optional

# Production install (skip devDependencies)
bun install --production

# Frozen lockfile (don't update)
bun install --frozen-lockfile

Cache Management

# Clear Bun cache
bun pm cache rm

# Check cache size
bun pm cache

Parallel Installation

Bun installs packages in parallel automatically, making it significantly faster than npm/yarn/pnpm.

Troubleshooting

Check Package Info

# View package details
bun pm ls express

# View all dependencies
bun pm ls

# Check for updates
bun outdated

Fixing Lockfile Issues

# Regenerate lockfile
rm bun.lockb
bun install

# Verify lockfile
bun install --frozen-lockfile

Related Skills

• bun-runtime: Understanding Bun's runtime for dependency usage
• bun-testing: Testing with Bun and managing test dependencies
• bun-bundler: Building projects with installed dependencies