Bun Lockfile Update Skill

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

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

Agent Skills: Bun Lockfile Update

Install this agent skill to your local

Skill Files