Bun Lockfile Update

Comprehensive guidance for updating Bun lockfiles (bun.lockb ) with proper dependency management practices.

When to Use

Use this skill automatically when:

• User requests lockfile update or dependency refresh

• User mentions outdated dependencies or security vulnerabilities

• User wants to update specific packages or all dependencies

• Lockfile conflicts occur during git operations

• User needs to audit or verify dependency integrity

Core Commands

Update All Dependencies

Update all dependencies to latest versions (respecting semver ranges in package.json)

bun update

Update all dependencies AND modify package.json to latest versions

bun update --latest

Update Specific Dependencies

Update specific package(s) to latest compatible version

bun update <package-name> bun update <package1> <package2>

Update specific package to latest version (ignoring semver range)

bun update --latest <package-name>

Regenerate Lockfile

Regenerate lockfile from package.json (clean install)

rm bun.lockb bun install

Or force regeneration

bun install --force

Update Strategies

1. Safe Update (Recommended)

Respects semver ranges in package.json :

Updates within semver constraints (^1.2.3 → 1.x.x, ~1.2.3 → 1.2.x)

bun update

Review changes

git diff bun.lockb package.json

Test thoroughly

bun test bun run build

When to use:

• Regular maintenance updates

• CI/CD pipeline updates

• Production deployments

• When stability is priority

2. Aggressive Update

Updates to absolute latest versions:

Updates AND modifies package.json to latest versions

bun update --latest

Review ALL changes carefully

git diff bun.lockb package.json

Test exhaustively (breaking changes likely)

bun test bun run build bun run lint

When to use:

• Major version upgrades

• Modernization efforts

• Security vulnerability fixes requiring latest versions

• Development/experimental branches

3. Selective Update

Updates specific packages only:

Update one critical package

bun update lodash

Update multiple related packages

bun update @types/node @types/react @types/react-dom

Update to latest version (ignore semver)

bun update --latest typescript

When to use:

• Targeted security patches

• Specific bug fixes

• Gradual migration strategies

• Reducing blast radius of changes

Best Practices Workflow

Pre-Update Checklist

Commit current state: Ensure clean working directory

git status git add . git commit -m "chore: checkpoint before dependency update"

Check for outdated packages:

bun outdated

Review security advisories:

bun audit

Update Process

• Choose strategy: Safe, aggressive, or selective

• Execute update command

• Review changes: git diff bun.lockb package.json

Post-Update Validation

Verify installation:

rm -rf node_modules bun install

Run test suite:

bun test

Run build:

bun run build

Run linting:

bun run lint

Check bundle size:

bun run build --analyze # If available

Test application manually:

• Critical user flows

• Edge cases

• Cross-browser testing (if web app)

Commit Changes

For safe updates

git add bun.lockb git commit -m "chore(deps): update dependencies

Updates all dependencies to latest compatible versions. All tests passing."

For aggressive updates

git add bun.lockb package.json git commit -m "chore(deps): upgrade dependencies to latest

BREAKING CHANGES:

• Updated React 17 → 18
• Updated TypeScript 4.9 → 5.3
• Updated Vite 4 → 5

See CHANGELOG for migration notes. All tests passing."

Common Scenarios

Scenario 1: Regular Maintenance

Goal: Keep dependencies fresh without breaking changes

Weekly/monthly routine

bun update bun test git add bun.lockb git commit -m "chore(deps): update dependencies"

Scenario 2: Security Vulnerability

Goal: Patch specific vulnerable package

Check vulnerability report

bun audit

Update vulnerable package to latest (may require --latest)

bun update --latest <vulnerable-package>

Verify fix

bun audit

Test and commit

bun test git add bun.lockb package.json git commit -m "fix(deps): patch security vulnerability in <package>

Fixes: CVE-XXXX-XXXXX"

Scenario 3: Major Version Upgrade

Goal: Migrate to new major version of framework/library

1. Create feature branch

git checkout -b chore/upgrade-react-18

2. Update target package

bun update --latest react react-dom

3. Update related packages

bun update --latest @types/react @types/react-dom

4. Review breaking changes documentation

(Check official migration guide)

5. Update code for breaking changes

(Fix deprecated APIs, adjust imports, etc.)

6. Run comprehensive tests

bun test bun run build bun run lint

7. Manual testing

(Test all critical flows)

8. Commit and create PR

git add . git commit -m "chore(deps): upgrade React 17 → 18

BREAKING CHANGES:

• Automatic batching changes render behavior
• Updated ReactDOM.render to createRoot
• Removed IE 11 support

See docs/migration/react-18.md for details."

Scenario 4: Lockfile Conflict Resolution

Goal: Resolve merge conflict in bun.lockb

1. Accept either version (doesn't matter which)

git checkout --theirs bun.lockb # Or --ours

2. Regenerate lockfile from package.json

rm bun.lockb bun install

3. Verify installation

bun test

4. Commit resolution

git add bun.lockb git commit -m "chore: resolve lockfile merge conflict"

Scenario 5: Dependency Audit & Cleanup

Goal: Remove unused dependencies and update remaining

1. Audit dependencies

bun pm ls # List installed packages

2. Check for unused dependencies

npx depcheck # Or manual review of package.json

3. Remove unused packages

bun remove <unused-package>

4. Update remaining dependencies

bun update

5. Verify everything still works

bun test bun run build

Bun-Specific Features

Binary Lockfile

• Bun uses binary lockfile format (bun.lockb )

• Much faster to parse than package-lock.json or yarn.lock

• Not human-readable (use bun pm ls to inspect)

Workspaces

Update all workspace packages

bun update

Update specific workspace

bun update --filter <workspace-name>

Compatibility

Install with npm/yarn compatibility

bun install --backend=npm

Generate package-lock.json for compatibility

bun install --lockfile-only

Troubleshooting

Lockfile Corruption

Symptoms: Install errors, checksum mismatches

Solution: Regenerate lockfile

rm bun.lockb bun install

Peer Dependency Conflicts

Symptoms: Peer dependency warnings during install

Solution: Update peer dependencies or use --force

bun install --force

Or resolve conflicts manually in package.json

Cache Issues

Clear Bun cache

rm -rf ~/.bun/install/cache

Reinstall

rm -rf node_modules bun.lockb bun install

Version Mismatch Errors

Symptoms: Package version doesn't match expectations

Solution: Verify package.json and regenerate lockfile

cat package.json # Check version ranges rm bun.lockb bun install

Security Best Practices

Regular Audits

Check for vulnerabilities

bun audit

Get detailed report

bun audit --json > audit-report.json

Automated Updates

Use Renovate or Dependabot for automated PRs

Configure in .github/renovate.json or .github/dependabot.yml

Review Dependencies

Before updating, review package reputation

Check npm package page, GitHub stars, maintenance status

bun pm ls <package-name>

Lockfile Integrity

Verify lockfile matches package.json

bun install --frozen-lockfile # CI/CD bun install --production --frozen-lockfile # Production

Integration with CI/CD

GitHub Actions Example

• name: Install dependencies run: bun install --frozen-lockfile

• name: Run tests run: bun test

• name: Update lockfile (scheduled job) run: | bun update bun test if: github.event_name == 'schedule'

Pre-commit Hook

.husky/pre-commit or similar

#!/bin/sh bun install --frozen-lockfile bun test

Related Skills

• Node.js Development - Modern JavaScript/TypeScript patterns with Bun

• Git Branch PR Workflow - Managing dependency update PRs

• GitHub Actions Inspection - Debugging CI/CD lockfile issues

References

• Bun CLI Documentation

• Bun Package Manager

• Bun Workspaces

• Semantic Versioning