bun-lockfile-update

Bun ロックファイルの更新

適切な依存関係管理の実践方法に基づいて、Bun のロックファイル（bun.lock）を更新するための包括的なガイダンスです。

このスキルを使用するタイミング

次の場合にこのスキルを使用します…	代わりに bun-outdated を使用します…
bun update を実行して依存関係を更新する場合	変更を加えずに古くなった依存関係を監査する場合
再生成によって bun.lock のマージコンフリクトを解決する場合	アップグレードを決める前にメジャーバージョンの差を確認する場合
特定のパッケージのセキュリティ脆弱性にパッチを適用する場合	単一のパッケージの新しいバージョンを一覧表示する場合
メジャーバージョンのアップグレードワークフローを実施する場合	新しいチェックアウトをセットアップする場合は bun-install を使用します

自動起動のトリガー

次の場合に、このスキルを自動的に使用します。

• ユーザーがロックファイルの更新または依存関係の更新をリクエストした場合
• ユーザーが古くなった依存関係またはセキュリティ脆弱性について言及した場合
• ユーザーが特定のパッケージまたはすべての依存関係を更新したい場合
• git 操作中にロックファイルのコンフリクトが発生した場合
• ユーザーが依存関係の整合性を監査または検証する必要がある場合

主なコマンド

すべての依存関係を更新する

# 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 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 from package.json (clean install)
rm bun.lock
bun install

# Or force regeneration
bun install --force

更新戦略

1. 安全な更新（推奨）

package.json の semver 範囲を尊重します。

# 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

使用するタイミング：

• 定期的なメンテナンス更新
• CI/CD パイプラインの更新
• 本番環境へのデプロイ
• 安定性を優先する場合

2. 積極的な更新

絶対的な最新バージョンに更新します。

# 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

使用するタイミング：

• メジャーバージョンのアップグレード
• モダナイゼーションの取り組み
• 最新バージョンが必要なセキュリティ脆弱性の修正
• 開発用／実験用ブランチ

3. 選択的な更新

特定のパッケージのみを更新します。

# 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

使用するタイミング：

• 対象を絞ったセキュリティパッチ
• 特定のバグ修正
• 段階的な移行戦略
• 変更の影響範囲を抑える場合

ベストプラクティスのワークフロー

更新前のチェックリスト

1. 現在の状態をコミットする： 作業ディレクトリがクリーンであることを確認します

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

2. 古くなったパッケージを確認する：

   bun outdated
   

3. セキュリティ勧告を確認する：

   bun audit
   

更新プロセス

1. 戦略を選択する： 安全、積極的、または選択的
2. 更新コマンドを実行する
3. 変更を確認する：

   git diff bun.lock package.json
   

更新後の検証

1. インストールを検証する：

   rm -rf node_modules
   bun install
   

2. テストスイートを実行する：

   bun test
   

3. ビルドを実行する：

   bun run build
   

4. リンターを実行する：

   bun run lint
   

5. バンドルサイズを確認する：

   bun run build --analyze  # If available
   

6. アプリケーションを手動でテストする：

   • 重要なユーザーフロー
   • エッジケース
   • クロスブラウザーテスト（ウェブアプリの場合）

変更をコミットする

# 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."

よくあるシナリオ

シナリオ 1：定期的なメンテナンス

目的： 破壊的変更を避けながら依存関係を最新に保つ

# Weekly/monthly routine
bun update
bun test
git add bun.lock
git commit -m "chore(deps): update dependencies"

シナリオ 2：セキュリティ脆弱性

目的： 脆弱性のある特定のパッケージにパッチを適用する

# 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"

シナリオ 3：メジャーバージョンのアップグレード

目的： フレームワーク／ライブラリの新しいメジャーバージョンに移行する

# 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."

シナリオ 4：ロックファイルのコンフリクト解決

目的： 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"

シナリオ 5：依存関係の監査と整理

目的： 未使用の依存関係を削除し、残りを更新する

# 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 固有の機能

ロックファイル形式（bun.lock）

• Bun 1.2 以降、デフォルトのロックファイルはテキスト形式の bun.lock（JSONC）です。人が読みやすく、git diff や PR で確認できます。
• 従来のバイナリ形式 bun.lockb も引き続きサポートされていますが、デフォルトではなくなりました。Bun ≥ 1.2 で bun install を実行すると、既存の bun.lockb は bun.lock に移行します（bun install --save-text-lockfile で強制できます）。
• テキスト形式のため、bun.lock のマージコンフリクトは確認でき、多くの場合その場で解決できます。ただし、（以下に示す）再生成が引き続き最も簡単な解決方法です。
• コミットするロックファイルは必ず 1 つだけにします。移行後は bun.lock を残し、古い bun.lockb があれば削除してください。

ワークスペース

# Update all workspace packages
bun update

# Update specific workspace
bun update --filter <workspace-name>

互換性

# Install with npm/yarn compatibility
bun install --backend=npm

# Generate package-lock.json for compatibility
bun install --lockfile-only

トラブルシューティング

ロックファイルの破損

# Symptoms: Install errors, checksum mismatches
# Solution: Regenerate lockfile
rm bun.lock
bun install

Peer Dependency のコンフリクト

# Symptoms: Peer dependency warnings during install
# Solution: Update peer dependencies or use --force
bun install --force

# Or resolve conflicts manually in package.json

キャッシュの問題

# Clear Bun cache
rm -rf ~/.bun/install/cache

# Reinstall
rm -rf node_modules bun.lock
bun install

バージョン不一致エラー

# 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

セキュリティのベストプラクティス

定期的な監査

# Check for vulnerabilities
bun audit

# Get detailed report
bun audit --json > audit-report.json

自動更新

依存関係の PR を自動化するには Renovate を使用してください。package.json にパッチを適用する際に、bun.lock をネイティブに再生成してコミットするため、更新やバージョン固定の PR では、追加設定なしで同期されたロックファイルが含まれます。

• bun プロジェクトで Dependabot を使用しないでください。 Dependabot は bun.lock を維持しないため、PR でロックファイルの同期が崩れます。Renovate に 一本化してください（.github/dependabot.yml を削除します）。
• postUpdateOptions に bun の値はありません。 許可されている値は npm/pnpm/yarn/bundler/go/nuget のみです。独自の値（例：bunDedupe）を指定すると、 Renovate の allowedValues 検証に失敗し、設定全体が機能しなくなります。更新時に一致するロックファイルを得るためのオプションは必要ありません。
• 定期的なロックファイル全体の更新には、lockFileMaintenance を有効にしてください（既定値は false なので、明示的に設定します）。Bun のこの機能に関するリグレッションは、Renovate PR #38694（2025 年 10 月）で修正されました。

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

依存関係のレビュー

# Before updating, review package reputation
# Check npm package page, GitHub stars, maintenance status
bun pm ls <package-name>

ロックファイルの整合性

# Verify lockfile matches package.json
bun install --frozen-lockfile  # CI/CD
bun install --production --frozen-lockfile  # Production

CI/CD との統合

GitHub Actions の例

- 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 フック

# .husky/pre-commit or similar
#!/bin/sh
bun install --frozen-lockfile
bun test

関連スキル

• Node.js 開発 - Bun を使用した最新の JavaScript/TypeScript パターン
• Git ブランチ PR ワークフロー - 依存関係更新 PR の管理
• GitHub Actions の調査 - CI/CD のロックファイルに関する問題のデバッグ

参考資料

• Bun CLI のドキュメント
• Bun パッケージマネージャー
• Bun ワークスペース
• セマンティックバージョニング