laurigates/bun-lockfile-update

Bun Lockfile Update

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

When to Use This Skill

| Use this skill when... | Use bun-outdated instead when... | |---|---| | Running bun update to refresh dependencies | Auditing what is outdated without changing anything | | Resolving a bun.lock merge conflict by regenerating | Reviewing major version gaps before deciding to upgrade | | Patching a security vulnerability in a specific package | Listing newer versions for a single package | | Performing a major version upgrade workflow | Use bun-install when bootstrapping a fresh checkout |

Auto-Invocation Triggers

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.lock
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.lock 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.lock 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

1. Commit current state: Ensure clean working directory

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

2. Check for outdated packages:

   bun outdated
   

3. Review security advisories:

   bun audit
   

Update Process

1. Choose strategy: Safe, aggressive, or selective
2. Execute update command
3. Review changes:

   git diff bun.lock package.json
   

Post-Update Validation

1. Verify installation:

   rm -rf node_modules
   bun install
   

2. Run test suite:

   bun test
   

3. Run build:

   bun run build
   

4. Run linting:

   bun run lint
   

5. Check bundle size:

   bun run build --analyze  # If available
   

6. Test application manually:

   • Critical user flows
   • Edge cases
   • Cross-browser testing (if web app)

Commit Changes

# For safe updates
git add bun.lock
git commit -m "chore(deps): update dependencies

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

# For aggressive updates
git add bun.lock 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.lock
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.lock 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.lock

# 1. Accept either version (doesn't matter which)
git checkout --theirs bun.lock  # Or --ours

# 2. Regenerate lockfile from package.json
rm bun.lock
bun install

# 3. Verify installation
bun test

# 4. Commit resolution
git add bun.lock
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

Lockfile Format (bun.lock)

• Since Bun 1.2 the default lockfile is the text-based bun.lock (JSONC) — human-readable and reviewable in git diff / PRs.
• The legacy binary bun.lockb is still supported but no longer the default; bun install under Bun ≥ 1.2 migrates an existing bun.lockb to bun.lock (force it with bun install --save-text-lockfile).
• Because it is text, bun.lock merge conflicts can be reviewed and often resolved directly — though regenerating (below) is still the simplest fix.
• Commit exactly one lockfile: keep bun.lock and delete any stale bun.lockb once migrated.

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.lock
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.lock
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.lock
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 for automated dependency PRs — it regenerates and commits bun.lock natively when it patches package.json, so update/pin PRs ship a synchronized lockfile with no extra configuration.

• Do not use Dependabot for bun projects. Dependabot does not maintain bun.lock, so its PRs leave the lockfile out of sync. Consolidate on Renovate (remove .github/dependabot.yml).
• There is no bun value for postUpdateOptions. The allowed values are npm/pnpm/yarn/bundler/go/nuget only; an invented value (e.g. bunDedupe) fails Renovate's allowedValues validation and breaks the entire config. No option is needed to get a matching lockfile on update.
• Enable lockFileMaintenance for the periodic full-lockfile refresh (its enabled defaults to false, so set it explicitly). Bun support for this was a regression fixed in Renovate PR #38694 (Oct 2025).

// renovate.json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "lockFileMaintenance": { "enabled": true }
}

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