はじめに
npmパッケージのバージョンアップは、互換性の問題やバグが起きやすいポイント。
安易に一気に全部上げるのではなく、段階的に・細かくチェックしながら進めるのがおすすめです。
本記事では、
- 従来のコマンドベースの手動アップデート方法
- npm-check-updates（ncu）ライブラリを使った効率的な方法
の2パターンをご紹介し、ブランチ管理も含めた安全な作業フローを解説します。
前提知識
Semantic Versioning
バージョンは通常 MAJOR.MINOR.PATCH の3つの数字で構成されます。
- MAJOR: 後方互換性のない大きな変更があったときに上げる
- MINOR: 後方互換性のある新機能追加があったときに上げる
- PATCH: バグ修正などの小さな変更があったときに上げる
例）1.4.2 → メジャー1、マイナー4、パッチ2
バージョン指定の記号 ^ と ~
^1.2.3 → マイナーアップデートまで許容
（例：1.3.0や1.4.5にはアップデートされるが、2.0.0は不可）
~1.2.3 → パッチアップデートまで許容
（例：1.2.4や1.2.9にはアップデートされるが、1.3.0は不可）
これらはpackage.jsonの依存関係でよく使われ、アップデートの範囲を指定します。
準備：新しいブランチを切る
git checkout -b <branch-name>
メインブランチに直接変更を加えず、問題が起きた場合にすぐに切り戻せるよう、必ず別ブランチで作業しましょう。
手動でバージョンアップする方法
1. 現状のアップデート可能なパッケージを確認
npm outdated
出力結果：
@eslint/jsは現在v9.17.0ですが、v9.32.0が最新版なのでマイナー、
@hookform/resolversは現在v3.10.0ですが、v5.2.1が最新版なのでメージャー、
autoprefixerは現在v10.4.20ですが、v10.4.21が最新版なのでパッチの
アップデートが必要そうですね。
2. minorとpatchバージョンをアップデート
npm update
npm update は、package.jsonに書かれたバージョン指定の範囲内（^や~に基づく）で最新版に更新してくれます。マイナー・パッチアップデートは通常後方互換性が保たれているので、一気に上げてしまっても壊れにくいです。
アップデート後は忘れずにコミットをしましょう。
git add package.json package-lock.json
git commit -m "Update minor and patch dependencies"
3. majorアップデートは慎重に実施
メジャーアップデートは後方互換性が壊れる可能性があるため、慎重に行う必要があります。パッケージを一つずつ個別にアップデートしていきましょう。
npm install <package>@latest
アップデート後にやるべきこと：
- 公式ドキュメントやchangelog、migration guideを読み、破壊的変更の内容を確認
- 変更点を理解した上で必要であればコードを編集
- テストを実施し問題なく通るか検証
無事に終わったらこちらもコミットを忘れずに。
git add package.json package-lock.json
git commit -m "Major update for <package>"
npm-check-updates(ncu)を使ったバージョンアップ方法
導入方法
npm install -g npm-check-updates
patchバージョンアップデート
ncu -t patch
ncu -u -t patch
npm install
git add package.json package-lock.json
git commit -m "Update patch dependencies"
解説：
-
ncu -t patchでパッチアップデートできる対象を確認 -
ncu -u -t patchでパッチアップデートを実行し、package.jsonのバージョン指定を更新 -
npm installで実際に依存パッケージをインストール（更新） - 変更された package.json と package-lock.json をステージしてコミット
minorバージョンアップデート
ncu -u -t minor
npm install
git add package.json package-lock.json
git commit -m "Update minor dependencies"
-
ncu -t minorでマイナーアップデートできる対象を確認 -
ncu -u -t minorでマイナーアップデートを実行し、package.jsonのバージョン指定を更新 -
npm installで実際に依存パッケージをインストール（更新） - 変更された package.json と package-lock.json をステージしてコミット
3. majorバージョンアップデート
ncu
npm install <package>@latest
git add package.json package-lock.json
git commit -m "Major update for <package>"
-
ncuでメジャーアップデートできる対象を確認 -
npm install <package>@latestで個別にメジャーアップデート - (破壊的内容の確認、コード修正、テスト検証)
- 変更された package.json と package-lock.json をステージしてコミット
まとめ
個人的にはncuを使ったやり方の方が簡単だし、patchやminorアップデートも段階的に実施できるのでそちらをお勧めします。