Skip to content
package.jsonの更新はnpm-check-updatesにおまかせ!記事のサムネイル

package.jsonの更新はnpm-check-updatesにおまかせ! ​

みなさんはpackage.jsonの依存パッケージをどうやってアップデートしているでしょうか。 npm outdatedで確認して、ひとつずつnpm install パッケージ名@latestをしていくのは結構面倒です。 私はnpm-check-updatesというライブラリを愛用しています。 お気に入りのライブラリで、ぜひ知ってもらいたいので記事にまとめてみました。

GitHub - raineorshine/npm-check-updates: Find newer versions of package dependencies than what your package.json allowshttps://github.com/raineorshine/npm-check-updates
GitHub - raineorshine/npm-check-updates: Find newer versions of package dependencies than what your package.json allows

動作確認環境

  • 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でグローバルにインストールしています。

bash
mise use -g npm:npm-check-updates

npmでグローバルにインストールしてもいいですし、npx npm-check-updatesでインストールせずに使うこともできます。 コマンドはncuです。

基本の使い方 ​

更新できるパッケージを確認する ​

bash
ncu
bash
Patch   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

Patch、Minor、Majorに分けて表示してくれます。 この時点ではpackage.jsonは書き換わりません。

まとめて更新する ​

bash
ncu -u

表示されたパッケージをすべてpackage.jsonに書き込みます。 メジャーアップデートも含めて全部上がってしまうので、私は使ったことがありません。

対話モードで選んで更新する ​

私はいつもこれを使っています。

bash
ncu -i
bash
Patch   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 ​

公開されてから一定期間が経ったバージョンだけを対象にするオプションです。

bash
ncu -i --cooldown 7
bash
Major   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です。

bash
ncu -i -c 7d

v22からの変更

v21までは、最新バージョンが期間内だとそのパッケージ自体がスキップされていました。 v22からは、期間を過ぎたバージョンの中で一番新しいものにフォールバックしてくれるようになりました。上の例で26.1.1が提案されているのはこのためです。 以前の挙動にしたい場合は--target "@latest"を付けます。

さらにv20からは、--cooldownを指定しなくても、パッケージマネージャー側の設定を自動で読み込んでくれるようになりました。

パッケージマネージャー読み込む設定
npm.npmrcのmin-release-age
yarn.yarnrc.ymlのnpmMinimalAgeGate
pnpmpnpm-workspace.yamlのminimumReleaseAge

私の環境では.npmrcにmin-release-ageを設定しているので、ncuを実行すると最初に下記のように表示されます。

bash
Using min-release-age from .npmrc: 7 days

peer ​

インストール済みパッケージのpeer依存を考慮して、互換性のあるバージョンに絞ってくれるオプションです。

bash
ncu -i --peer
bash
Patch   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未満に制限されているためです。

json
"peerDependencies": {
  "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
  "typescript": ">=4.8.4 <6.1.0"
}

--peerなしでTypeScriptを7系に上げると、インストール時にpeer依存のエラーや警告が出てしまいます。

対象外になったアップデートは、理由と一緒に一覧の下に表示されます。

bash
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 ​

どこまでバージョンを上げるかを指定するオプションです。

bash
# メジャーバージョンは上げずに、マイナーとパッチだけ
ncu --target minor

# パッチだけ
ncu --target patch

デフォルトはlatestで、npmのlatestタグが付いたバージョンまで上げます。

filter / reject ​

対象にするパッケージを絞り込んだり、除外したりできます。ワイルドカードや正規表現も使えます。

bash
# eslintで始まるパッケージだけ
ncu --filter "eslint*"

# typescriptは除外
ncu --reject typescript

doctorモード ​

doctorモードは、テストを実行しながらアップデートして、テストを壊すパッケージを特定してくれる機能です。

bash
ncu --doctor -u

-uを付けないと、ヘルプが表示されるだけで実行されません。流れは下記のとおりです。

  1. npm installとnpm testを実行して、今の状態でテストが通ることを確認する
  2. ncu -uですべてのパッケージをアップデートして、テストを実行する
  3. テストが通れば終わり
  4. テストが落ちたら、package.jsonとlock fileを元に戻す
  5. パッケージをひとつずつアップデートしては、テストを実行する
  6. テストを壊したパッケージを、エラー内容と一緒に表示する
  7. テストが通ったパッケージだけをpackage.jsonに保存する

実際に試してみる ​

せっかくなので、わざとテストが壊れるようなプロジェクトを用意して試してみました。 chalkはv5からESM専用になったので、v4の感覚でrequireしているとテストが落ちるはずです。

json
{
  "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"
  }
}
js
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つとも更新できる状態です。

bash
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.0

doctorモードを実行してみます。

bash
ncu --doctor -u
bash
Running 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つはアップデートされています。

json
"dependencies": {
  "chalk": "^4.1.2",
  "is-number": "^7.0.0",
  "ms": "^2.1.3"
}

テストを実行するコマンドは--doctorTest、インストールするコマンドは--doctorInstallで変えられます。

bash
ncu --doctor -u --doctorTest "npm run test:unit"

なお、アップデート前の時点でテストが落ちていると、Tests failed before we even got started!と表示されて何も変更せずに終わります。

当然ですが、テストがしっかり書かれていないと「テストは通ったけど壊れている」ということになります。 また、package.json、lock file、node_modulesを直接書き換えるので、コミットしてきれいな状態で実行するのがよさそうです。

設定ファイル ​

ここまで紹介したオプションは、毎回打つのも覚えるのも大変です。 .ncurc.jsonに書いておけば、ncuだけで同じように動いてくれます。

json
{
  "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やドキュメントを見てみてください。