package.jsonの更新はnpm-check-updatesにおまかせ!
みなさんはpackage.jsonの依存パッケージをどうやってアップデートしているでしょうか。 npm outdatedで確認して、ひとつずつnpm install パッケージ名@latestをしていくのは結構面倒です。 私はnpm-check-updatesというライブラリを愛用しています。 お気に入りのライブラリで、ぜひ知ってもらいたいので記事にまとめてみました。
動作確認環境
- npm-check-updates:v23.1.1
- Node.js:v26.13.0
- npm:v11.20.0
記事内の出力例は、説明のために一部を省略しています。
npm-check-updatesとは
package.jsonの依存パッケージの新しいバージョンを調べて、まとめてアップデートできるCLIツールです。GitHubのスター数や週のダウンロード数は以下です。(2026年11月19日時点)
- GitHubのスター:約1万
- 週間ダウンロード:約86万
npm updateとの大きな違いは、package.jsonに書かれたバージョンの範囲を超えてアップデートできるところです。 npm updateは、package.jsonに書かれた範囲の中でしか更新しません。たとえば@types/nodeが^24.13.3なら、24系の最新までは上がりますが、26系には上がりません。 また、デフォルトではpackage.jsonは書き換えず、node_modulesとlock fileだけを更新します。 npm-check-updatesは、package.jsonの^24.13.3を^26.1.2に書き換えるといったことができます。
インストール
いろんなリポジトリで使いたいので、私はmiseでグローバルにインストールしています。
mise use -g npm:npm-check-updatesnpmでグローバルにインストールしてもいいですし、npx npm-check-updatesでインストールせずに使うこともできます。 コマンドはncuです。
基本の使い方
更新できるパッケージを確認する
ncuPatch Backwards-compatible bug fixes
@types/react ^19.2.17 → ^19.2.18
@types/react-dom ^19.2.3 → ^19.2.4
@vitejs/plugin-react ^6.0.4 → ^6.0.5
Minor Backwards-compatible features
globals ^17.7.0 → ^17.8.0
Major Potentially breaking API changes
@types/node ^24.13.3 → ^26.1.2
typescript ~6.0.2 → ~7.0.2Patch、Minor、Majorに分けて表示してくれます。 この時点ではpackage.jsonは書き換わりません。
まとめて更新する
ncu -u表示されたパッケージをすべてpackage.jsonに書き込みます。 メジャーアップデートも含めて全部上がってしまうので、私は使ったことがありません。
対話モードで選んで更新する
私はいつもこれを使っています。
ncu -iPatch Backwards-compatible bug fixes
❯ ◉ @types/react ^19.2.17 → ^19.2.18
◉ @types/react-dom ^19.2.3 → ^19.2.4
◉ @vitejs/plugin-react ^6.0.4 → ^6.0.5
Minor Backwards-compatible features
◉ globals ^17.7.0 → ^17.8.0
Major Potentially breaking API changes
◯ @types/node ^24.13.3 → ^26.1.2
◯ typescript ~6.0.2 → ~7.0.2スペースキーで選んで、Enterで確定します。 PatchとMinorは最初から選ばれていて、Majorは選ばれていない状態で始まるので、そのままEnterを押すだけで安全な更新だけを取り込めます。 確定するとpackage.jsonが書き換わり、続けてインストールするかどうかも聞いてくれます。
よく使うオプション
オプションがとても豊富で全部は把握しきれていませんが、私がよく使うものを紹介します。
cooldown
公開されてから一定期間が経ったバージョンだけを対象にするオプションです。
ncu -i --cooldown 7Major Potentially breaking API changes
❯ ◯ @types/node ^24.13.3 → ^26.1.1 [cooldown] 26.1.2
◯ typescript ~6.0.2 → ~7.0.2上記の場合、公開から7日経っていない@types/nodeの26.1.2は対象外になり、代わりに7日経っている26.1.1が提案されています。
公開直後のバージョンには、不具合のあるものや、乗っ取られたアカウントから公開された悪意のあるものが紛れていることがあります。少し待ってから取り込むことで、こうしたサプライチェーン攻撃のリスクを減らせます。 Renovateとpnpmで同じことをした話はRenovateとpnpmで公開から7日経ったバージョンだけPRを作成するに書きました。
期間は7のような数字(日数)のほかに、7d、12h、30mのように単位を付けて書くこともできます。短縮形は-cです。
ncu -i -c 7dv22からの変更
v21までは、最新バージョンが期間内だとそのパッケージ自体がスキップされていました。 v22からは、期間を過ぎたバージョンの中で一番新しいものにフォールバックしてくれるようになりました。上の例で26.1.1が提案されているのはこのためです。 以前の挙動にしたい場合は--target "@latest"を付けます。
さらにv20からは、--cooldownを指定しなくても、パッケージマネージャー側の設定を自動で読み込んでくれるようになりました。
| パッケージマネージャー | 読み込む設定 |
|---|---|
| npm | .npmrcのmin-release-age |
| yarn | .yarnrc.ymlのnpmMinimalAgeGate |
| pnpm | pnpm-workspace.yamlのminimumReleaseAge |
私の環境では.npmrcにmin-release-ageを設定しているので、ncuを実行すると最初に下記のように表示されます。
Using min-release-age from .npmrc: 7 dayspeer
インストール済みパッケージのpeer依存を考慮して、互換性のあるバージョンに絞ってくれるオプションです。
ncu -i --peerPatch Backwards-compatible bug fixes
❯ ◉ @types/react ^19.2.17 → ^19.2.18
◉ @types/react-dom ^19.2.3 → ^19.2.4
◉ @vitejs/plugin-react ^6.0.4 → ^6.0.5
◉ typescript ~6.0.2 → ~6.0.3
Minor Backwards-compatible features
◉ globals ^17.7.0 → ^17.8.0
Major Potentially breaking API changes
◯ @types/node ^24.13.3 → ^26.1.2--peerなしでは7.0.2だったTypeScriptが、6.0.3になっています。 これはtypescript-eslintのpeerDependenciesで、TypeScriptが6.1.0未満に制限されているためです。
"peerDependencies": {
"eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
"typescript": ">=4.8.4 <6.1.0"
}--peerなしでTypeScriptを7系に上げると、インストール時にpeer依存のエラーや警告が出てしまいます。
対象外になったアップデートは、理由と一緒に一覧の下に表示されます。
Ignored incompatible updates (peer dependencies):
typescript ~6.0.2 → ~7.0.2 reason: typescript-eslint requires >=4.8.4 <6.1.0なお、typescript-eslint自体にも新しいバージョンがある場合は、TypeScriptではなくtypescript-eslintのほうが対象外になることもありました。どちらが残るかは状況によるので、表示された理由を確認しておくと安心です。
target
どこまでバージョンを上げるかを指定するオプションです。
# メジャーバージョンは上げずに、マイナーとパッチだけ
ncu --target minor
# パッチだけ
ncu --target patchデフォルトはlatestで、npmのlatestタグが付いたバージョンまで上げます。
filter / reject
対象にするパッケージを絞り込んだり、除外したりできます。ワイルドカードや正規表現も使えます。
# eslintで始まるパッケージだけ
ncu --filter "eslint*"
# typescriptは除外
ncu --reject typescriptdoctorモード
doctorモードは、テストを実行しながらアップデートして、テストを壊すパッケージを特定してくれる機能です。
ncu --doctor -u-uを付けないと、ヘルプが表示されるだけで実行されません。流れは下記のとおりです。
npm installとnpm testを実行して、今の状態でテストが通ることを確認するncu -uですべてのパッケージをアップデートして、テストを実行する- テストが通れば終わり
- テストが落ちたら、package.jsonとlock fileを元に戻す
- パッケージをひとつずつアップデートしては、テストを実行する
- テストを壊したパッケージを、エラー内容と一緒に表示する
- テストが通ったパッケージだけをpackage.jsonに保存する
実際に試してみる
せっかくなので、わざとテストが壊れるようなプロジェクトを用意して試してみました。 chalkはv5からESM専用になったので、v4の感覚でrequireしているとテストが落ちるはずです。
{
"name": "ncu-doctor-demo",
"private": true,
"scripts": {
"test": "node test.cjs"
},
"dependencies": {
"chalk": "^4.1.2",
"is-number": "^6.0.0",
"ms": "^2.0.0"
}
}const assert = require('node:assert')
const chalk = require('chalk')
const isNumber = require('is-number')
const ms = require('ms')
assert.strictEqual(chalk.red('a').includes('a'), true)
assert.strictEqual(isNumber(5), true)
assert.strictEqual(ms('1s'), 1000)
console.log('all tests passed')ncuで確認すると、3つとも更新できる状態です。
Minor Backwards-compatible features
ms ^2.0.0 → ^2.1.3
Major Potentially breaking API changes
chalk ^4.1.2 → ^6.0.1
is-number ^6.0.0 → ^7.0.0doctorモードを実行してみます。
ncu --doctor -uRunning tests before upgrading
npm install
npm run test
all tests passed
Upgrading all dependencies and re-running tests
ncu -u
npm install
npm run test
TypeError: chalk.red is not a function
Tests failed
Identifying broken dependencies
npm install
npm install --no-save chalk@^6.0.1
npm run test
TypeError: chalk.red is not a function
✗ chalk ^4.1.2 → ^6.0.1
npm install --no-save is-number@^7.0.0
npm run test
all tests passed
✓ is-number ^6.0.0 → ^7.0.0
npm install --no-save ms@^2.1.3
npm run test
all tests passed
✓ ms ^2.0.0 → ^2.1.3
Saving partially upgraded package.json
npm install全部上げるとテストが落ちたので、ひとつずつ試して、chalkが原因だと特定してくれました。 実行後のpackage.jsonは、chalkだけが元のままで、残りの2つはアップデートされています。
"dependencies": {
"chalk": "^4.1.2",
"is-number": "^7.0.0",
"ms": "^2.1.3"
}テストを実行するコマンドは--doctorTest、インストールするコマンドは--doctorInstallで変えられます。
ncu --doctor -u --doctorTest "npm run test:unit"なお、アップデート前の時点でテストが落ちていると、Tests failed before we even got started!と表示されて何も変更せずに終わります。
当然ですが、テストがしっかり書かれていないと「テストは通ったけど壊れている」ということになります。 また、package.json、lock file、node_modulesを直接書き換えるので、コミットしてきれいな状態で実行するのがよさそうです。
設定ファイル
ここまで紹介したオプションは、毎回打つのも覚えるのも大変です。 .ncurc.jsonに書いておけば、ncuだけで同じように動いてくれます。
{
"interactive": true,
"cooldown": 7,
"peer": true
}これでncuを実行すると、ncu -i -c 7 --peerと同じ動きになります。
設定ファイルは、ncuを実行したディレクトリから親のディレクトリへ順に探していき、最初に見つかったものが使われます。探すのはホームディレクトリまでです。
そのため、ホームディレクトリに置いておけば、ホームディレクトリ配下のどのリポジトリでも使えます。 リポジトリごとに変えたい場合は、そのリポジトリにも設定ファイルを置きます。
WARNING
リポジトリに設定ファイルがあると、ホームディレクトリの設定ファイルは読み込まれません。2つの設定が合わさるわけではないので、ホームディレクトリと同じ設定も必要なら、リポジトリ側にも書いておく必要があります。 なお、READMEには「設定はマージされる」と書かれていますが、v23.1.1で試した限りでは、最初に見つかった設定ファイルだけが使われました。 また、コマンドラインで指定したオプションは、設定ファイルより優先されます。
拡張子なしの.ncurc(JSONかYAML)や、.ncurc.jsなども使えます。filterなどに関数を渡したい場合はJSのファイルにします。
まとめ
npm-check-updatesを紹介しました。 対話モードで選んで更新するだけでも十分便利ですが、cooldownやpeerを組み合わせると、より安全にアップデートできます。 doctorモードも、テストがしっかりあるリポジトリでは便利そうです。 オプションはここで紹介したもの以外にもたくさんあるので、気になった方はncu --helpやドキュメントを見てみてください。