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

bash

# Create package.json
bun init

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

Installing Dependencies

bash

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

# Shorthand
bun i

Adding Dependencies

bash

# 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

bash

# Remove dependency
bun remove lodash

# Remove multiple dependencies
bun remove react react-dom

Updating Dependencies

bash

# Update all dependencies
bun update

# Update specific dependency
bun update lodash

# View updatable dependencies
bun outdated

package.json Management

Dependency Types

json

{
  "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:

bash

# 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

bash

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

Global Package Management

Installing Global Packages

bash

# Install global package
bun add --global typescript

# Shorthand
bun add -g typescript

Viewing Global Packages

bash

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

Removing Global Packages

bash

bun remove -g typescript

Registry Configuration

Using Mirror Sources

bash

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

Configuration File

Create bunfig.toml:

toml

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

Multiple Registry Configuration

toml

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

# Other packages use default registry

Workspaces (Monorepo)

Configuring Workspaces

json

// 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

bash

# 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

bash

# View cache directory
echo $BUN_INSTALL/install/cache

Clearing Cache

bash

# Clear package cache
bun pm cache rm

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

Offline Installation

bash

# Prefer using cache
bun install --prefer-offline

# Fully offline installation
bun install --offline

Advanced Installation Options

Installation Options

bash

# 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

bash

# 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

json

{
  "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

bash

# 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:

bash

# 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

bash

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

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

Version Conflicts

bash

# View conflict reason
bun pm why conflicting-package

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

Private Package Authentication

toml

# 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 ​

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