Bun Lockfile Update

Bun Lockfile Update

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

When to Use This Skill

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

Step-by-step sequences for regular maintenance, a security vulnerability, a major version upgrade, a bun.lock merge conflict, and a dependency audit are in references/scenarios.md.

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

For lockfile corruption, peer dependency conflicts, cache issues, and version mismatch errors, see references/troubleshooting.md.

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