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