Bun Package Manager

Bun has a built-in lightning-fast package manager that can replace npm, yarn, and pnpm. This chapter introduces how to use the Bun package manager and its advanced features.

Why Use Bun Package Manager?

Speed Comparison

Time comparison for installing React project dependencies:
┌────────────────────────────────────────────┐
│ npm    ████████████████████████████  30s   │
│ yarn   ██████████████████████        22s   │
│ pnpm   ████████████████              16s   │
│ bun    ██                            1.5s  │
└────────────────────────────────────────────┘

Advantages of Bun package manager:

Lightning-fast installation: 20-30x faster than npm
Hard links: Save disk space
Compatibility: Fully compatible with npm ecosystem
Zero configuration: No additional setup required

Basic Commands

Initializing Projects

# Create package.json
bun init

# Interactive creation
bun init -y  # Skip prompts, use defaults

Installing Dependencies

# Install all dependencies (according to package.json)
bun install

# Shorthand
bun i

Adding Dependencies

# Add production dependency
bun add lodash

# Add multiple dependencies
bun add react react-dom

# Add dev dependency
bun add -d typescript @types/node

# Add optional dependency
bun add --optional fsevents

# Add exact version
bun add express@4.18.2

# Add specified version range
bun add "express@^4.18.0"

Removing Dependencies

# Remove dependency
bun remove lodash

# Remove multiple dependencies
bun remove react react-dom

Updating Dependencies

# Update all dependencies
bun update

# Update specific dependency
bun update lodash

# View updatable dependencies
bun outdated

package.json Management

Dependency Types

{
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "@types/node": "^20.0.0"
  },
  "peerDependencies": {
    "react": "^18.0.0"
  },
  "optionalDependencies": {
    "fsevents": "^2.3.0"
  }
}

Version Specifiers

Syntax	Meaning
`4.18.2`	Exact version
`^4.18.0`	Compatible version (4.x.x)
`~4.18.0`	Patch version (4.18.x)
`*`	Any version
`>=4.18.0`	Greater than or equal to specified version
`4.18.0 - 5.0.0`	Version range

Lock File

bun.lockb

Bun uses a binary lock file bun.lockb:

# View lock file content (convert to yarn.lock format)
bun bun.lockb

Lock File Advantages

Smaller: Much smaller than package-lock.json
Faster: Binary format parses faster
Deterministic: Ensures consistent installation results

Ignoring Lock File

# Reinstall without saving lock file
bun install --no-save

Global Package Management

Installing Global Packages

# Install global package
bun add --global typescript

# Shorthand
bun add -g typescript

Viewing Global Packages

# Global package location
ls ~/.bun/install/global

Removing Global Packages

bun remove -g typescript

Registry Configuration

Using Mirror Sources

# Temporarily use mirror
bun add lodash --registry https://registry.npmmirror.com

Configuration File

Create bunfig.toml:

[install]
# Use domestic mirror
registry = "https://registry.npmmirror.com"

Multiple Registry Configuration

[install.scopes]
# @company scope uses private registry
"@company" = "https://npm.company.com"

# Other packages use default registry

Workspaces (Monorepo)

Configuring Workspaces

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

Directory Structure

my-monorepo/
├── package.json
├── packages/
│   ├── shared/
│   │   └── package.json
│   └── utils/
│       └── package.json
├── apps/
│   ├── web/
│   │   └── package.json
│   └── api/
│       └── package.json
└── bun.lockb

Workspace Commands

# Install all workspace dependencies
bun install

# Run command in specific workspace
bun run --filter @company/web dev

# Add dependency to specific workspace
bun add lodash --filter @company/web

# Add dependency between workspaces
bun add @company/shared --filter @company/web

Cache Management

Cache Location

# View cache directory
echo $BUN_INSTALL/install/cache

Clearing Cache

# Clear package cache
bun pm cache rm

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

Offline Installation

# Prefer using cache
bun install --prefer-offline

# Fully offline installation
bun install --offline

Advanced Installation Options

Installation Options

# Only install production dependencies
bun install --production

# Freeze lock file (recommended for CI)
bun install --frozen-lockfile

# Don't execute lifecycle scripts
bun install --ignore-scripts

# Force reinstall
bun install --force

Viewing Dependency Tree

# View dependency tree
bun pm ls

# View specific package dependencies
bun pm ls lodash

# View why a package was installed
bun pm why lodash

Publishing Packages

Preparing for Publish

{
  "name": "@username/my-package",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "bun build src/index.ts --outdir dist",
    "prepublishOnly": "bun run build"
  }
}

Publishing to npm

# Login to npm
npm login

# Publish package
npm publish

# Publish scoped package
npm publish --access public

Comparison with Other Package Managers

Command Comparison

Operation	npm	yarn	pnpm	bun
Install dependencies	`npm install`	`yarn`	`pnpm install`	`bun install`
Add dependency	`npm install pkg`	`yarn add pkg`	`pnpm add pkg`	`bun add pkg`
Add dev dependency	`npm install -D pkg`	`yarn add -D pkg`	`pnpm add -D pkg`	`bun add -d pkg`
Remove dependency	`npm uninstall pkg`	`yarn remove pkg`	`pnpm remove pkg`	`bun remove pkg`
Run script	`npm run cmd`	`yarn cmd`	`pnpm cmd`	`bun run cmd`
Global install	`npm install -g pkg`	`yarn global add pkg`	`pnpm add -g pkg`	`bun add -g pkg`

Migrating to Bun

Migrating from other package managers is very simple:

# Delete old lock file and node_modules
rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml

# Reinstall using Bun
bun install

Common Issues

Installation Failure

# Clean and retry
rm -rf node_modules bun.lockb
bun install

# Use verbose mode to see errors
bun install --verbose

Version Conflicts

# View conflict reason
bun pm why conflicting-package

# Force use specific version
bun add package@version --force

Private Package Authentication

# bunfig.toml
[install.scopes]
"@private" = { url = "https://npm.private.com", token = "$NPM_TOKEN" }

Summary

This chapter introduced:

✅ Bun package manager basic commands
✅ Dependency management and version control
✅ Registry and mirror configuration
✅ Workspaces (Monorepo) support
✅ Cache management and offline installation
✅ Migrating from other package managers

Next Steps

Continue reading Module System to learn about Bun's support for ES Modules and CommonJS.

#Bun Package Manager

#Why Use Bun Package Manager?

#Speed Comparison

#Basic Commands

#Initializing Projects

#Installing Dependencies

#Adding Dependencies

#Removing Dependencies

#Updating Dependencies

#package.json Management

#Dependency Types

#Version Specifiers

#Lock File

#bun.lockb

#Lock File Advantages

#Ignoring Lock File

#Global Package Management

#Installing Global Packages

#Viewing Global Packages

#Removing Global Packages

#Registry Configuration

#Using Mirror Sources

#Configuration File

#Multiple Registry Configuration

#Workspaces (Monorepo)

#Configuring Workspaces

#Directory Structure

#Workspace Commands

#Cache Management

#Cache Location

#Clearing Cache

#Offline Installation

#Advanced Installation Options

#Installation Options

#Viewing Dependency Tree

#Publishing Packages

#Preparing for Publish

#Publishing to npm

#Comparison with Other Package Managers

#Command Comparison

#Migrating to Bun

#Common Issues

#Installation Failure

#Version Conflicts

#Private Package Authentication

#Summary

#Next Steps