npm-check-updates

npm-check-updates (ncu)

npm-check-updates は、既存のバージョン範囲ポリシー（^17.0.2 → ^18.3.1）を維持したまま、package.json の依存関係を最新バージョンにアップグレードします。変更するのは package.json のみです。package-lock.json と node_modules を更新するには、ユーザーがパッケージマネージャーのインストールコマンド（例：npm install）を実行する必要があります。

CLI は npm-check-updates と、より短い ncu として提供されています。このライブラリは純粋な ESM で、Node からインポートでき（CommonJS からは require() で読み込めます）。

このスキルを使う場面

• プロジェクト内の古い依存関係を一覧表示する。
• package.json のバージョンを入手可能な最新のものに更新する（ドライラン、対話形式、またはディスクへの書き込み）。
• フィルター、除外指定、ピア依存関係の考慮、またはエンジン制約を使って一括アップグレードする。
• モノレポをスキャンする（ワークスペース、--deep、カスタム glob）。
• クールダウン期間や反復的な --doctor モードを使って、より安全にアップグレードする。
• Node スクリプトまたは .ncurc.* 設定から ncu をプログラムで実行する。

クイックスタート

# Dry run: print upgrades without touching files.
ncu

# Write the upgrades back into package.json, then install.
ncu -u
npm install

# Interactively pick which packages to upgrade.
ncu -i

# Only a subset of packages.
ncu -f "react,react-dom"
ncu "/^@types\//"

# Bump only patch / minor versions.
ncu --target patch
ncu --target minor

# Skip a package.
ncu -x typescript,eslint

主なフラグ

フラグ	目的
-u, --upgrade	package.json を上書きします（ドライラン以外の動作に必須です）。
-i, --interactive	チェックリストからパッケージを選択します。JSON 出力が設定されていない場合は、-u も有効になります。
-t, --target <value>	latest（デフォルト）、newest、greatest、minor、patch、semver、または @<tag>（例：@next、@beta）。
-f, --filter <p>	名前が一致するものだけを含めます。文字列、ワイルドカード、グロブ、カンマ区切りまたはスペース区切りのリスト、/regex/、または述語（.ncurc.js 内）を使用できます。
-x, --reject <p>	名前が一致するものを除外します。マッチャー構文は --filter と同じです。位置引数では ! を先頭に付けられます（ncu \!nodemon）。
-g, --global	ローカルプロジェクトではなく、グローバルにインストールされたパッケージを調べます。
-p, --packageManager <s>	npm、yarn、pnpm、deno、bun、または staticRegistry。
-d, --doctor	アップグレードごとにインストールとテストを反復して実行し、互換性を損なう変更を特定します。-u が必要です。
-c, --cooldown <period>	指定期間内に公開されたバージョンをスキップします。7／7d は日、12h は時間、30m は分です。サプライチェーンのリスクを軽減します。
--peer	バージョンを選択する際に、ピア依存関係の制約を尊重します。
--enginesNode	プロジェクトの engines.node と互換性のあるバージョンのみを対象にします。
--deep	cwd 配下のすべての package.json を再帰的に処理します。
-w, --workspaces	すべてのワークスペース（npm、yarn、pnpm）を処理します。ルートを除外するには --no-root と組み合わせます。
--workspace <s>	指定したワークスペースを処理します。ルートを除外するには --no-root と組み合わせます。
--packageFile <p>	デフォルトの package.json の場所を上書きします。グロブ（packages/*/package.json）を使用できます。
-j, --jsonAll	新しい package.json 全体を出力します。
--jsonDeps	--jsonAll と同様ですが、依存関係のフィールドのみを出力します。
--jsonUpgraded	アップグレードされた依存関係を JSON 形式で出力します。
--format <value>	カンマ区切りのリスト：dep、group、ownerChanged、repo、time、lines、installedVersion、cooldown。
-l, --loglevel <n>	silent、error、minimal、warn（デフォルト）、info、verbose、silly。
-e, --errorLevel <n>	1（デフォルト）または 2。2 は CI に適しており、更新が必要なものがない場合に終了コード 0 を返します。
--cache	レジストリへの問い合わせをキャッシュします。デフォルトのファイル：~/.ncu-cache.json。デフォルトの TTL：10 分。
--cacheFile <path>	キャッシュファイルのパス。
--cacheExpiration <min>	キャッシュ TTL（分）。
--registry <uri>	カスタムレジストリ。
--registryType <type>	npm（デフォルト）または json（静的 JSON カタログ）。
--install <value>	always、never、または prompt（デフォルト）。-u の後にインストールを実行しますか？
--pre <n>	プレリリースバージョンを含めます。--target newest または greatest の場合、および現在のバージョンがプレリリースの場合は自動的に有効になります。
--minimal	semver に従って範囲がすでに最新バージョンを満たしている場合は、アップグレードをスキップします。
--removeRange	範囲演算子を削除し、正確なバージョンに固定します。
--timeout <ms>	グローバルタイムアウト。リクエストごとのデフォルトは 30 秒です。
--retry <n>	レジストリへのリクエストが失敗した場合の再試行回数（デフォルト：3）。
--doctorInstall <cmd>	--doctor が使用するインストールコマンドを上書きします。
--doctorTest <cmd>	--doctor が使用するテストコマンドを上書きします。
--mergeConfig	--deep またはグロブと併用すると、見つかった各設定をルート設定とマージします。
--root	指定したワークスペースに加えて、ルートプロジェクトも含めます。
--stdin	標準入力から package.json を読み込みます。
--packageData <value>	package.json の内容を文字列として渡します。

設定ファイル（.ncurc.*）

ncu は次の場所から設定を読み込みます（後の設定が前の設定を上書きします）：CLI フラグ → ローカルの .ncurc.* → プロジェクトの .ncurc.* → $HOME/.ncurc.*。

対応するファイル形式：.ncurc、.ncurc.json、.ncurc.yaml、.ncurc.yml、.ncurc.js、.ncurc.mjs、.ncurc.cjs。

v21 以降、プロジェクトは純粋な ESM になったため、.ncurc.js では ESM の export default を使用してください。CJS 設定ファイルには .cjs を使用する必要があります。

述語関数を使用できるのは .ncurc.js のみです。例：

export default {
  filter: name => !name.startsWith('internal-'),
  reject: ['@types/*'],
  target: 'minor',
  cooldown: 7,
  doctor: false,
}

プログラム API

import ncu from 'npm-check-updates'

const upgraded = await ncu({
  packageFile: './packages/app/package.json',
  filter: ['react', 'react-dom'],
  target: 'latest',
  upgrade: true, // write back to disk
})

console.log(upgraded) // { 'react': '^18.3.1', 'react-dom': '^18.3.1' }

Node で直接実行します：

node ./scripts/check-deps.ts

推奨ワークフロー

最も安全なアップグレード手順

1. 作業ツリーがコミット済みであることを確認します。
2. 最近公開されたバージョンをスキップするには、ncu --cooldown 7 を実行します。
3. 更新を書き込むには、ncu -u を実行します。
4. npm install（または使用中のパッケージマネージャーに相当するコマンド）を実行します。
5. テストスイートを実行し、問題がなければコミットします。

破壊的なアップグレードを自動的に検出する

ncu --doctor -u

問題のあるアップグレードを一度に 1 つずつ元に戻し、原因となったパッケージを表示します。

モノレポ

# All workspaces, including the root.
ncu -uw

# All packages.json files under the cwd.
ncu --deep -u

# A specific glob, merging root config.
ncu --packageFile 'packages/*/package.json' --mergeConfig -u

カスタムレジストリ／プライベートミラー

ncu --registry https://npm.example.com --packageManager npm

# Or a static JSON catalog hosted anywhere.
ncu --registry https://example.com/versions.json --registryType json

注意点と落とし穴

• ncu が書き込むのは package.json のみです。ロックファイルと node_modules を更新するには、別途インストール手順が必要です。
• --doctor はロックファイルと node_modules を変更します。クリーンなツリーで使用してください。
• デフォルトの CLI 名 ncu は、一部のシステムで ncu-weather-cli や Nvidia CUDA の ncu と競合します。予期しない出力が表示された場合は、npm-check-updates を使用してください。
• Windows では、ncu が停止したように見える場合、--packageFile package.json を指定してください。標準入力を待っていることがあります。
• --cooldown を指定しない場合、クールダウン値は min-release-age（npm）、npmMinimalAgeGate（yarn）、または pnpm-workspace.yaml の minimumReleaseAge（pnpm）から読み取られます。
• v21.0.0 以降は純粋な ESM です。.ncurc.js は ESM（export default）である必要があります。CJS 設定ファイルには .cjs 拡張子が必要です。
• --format cooldown にはレジストリの時刻データが必要です。一部のミラーではこのデータを公開していません。何も報告されない場合は、パブリックレジストリを使用してください。

確認用チートシート

# Show all CLI options.
ncu --help

# Extended help for a single flag.
ncu --help --filter
ncu --help --target
ncu --help --cooldown
ncu --help --doctor