npm-check-and-update

A lightweight, zero-dependency CLI tool and Node.js library to check your package.json dependencies against the npm registry for available updates. Built using Node's native https module—no extra bloat added to your projects.

Note: Auto-updating package versions in package.json is planned for a future release (see Roadmap). Currently, this tool focuses exclusively on checking and reporting status.

Features

• Zero Runtime Dependencies: Lean and fast install with 0 external packages pulled in.
• Full Coverage: Scans dependencies, devDependencies, peerDependencies, and optionalDependencies.
• Concurrent Lookups: Checks multiple packages in parallel for rapid response times.
• Smart Directory Lookup: Finds the nearest package.json by walking up the folder tree—run it from any nested directory.
• CI-Ready: Exits with code 1 if outdated dependencies exist, and code 0 when clean.
• Dual Support: Works seamlessly as a terminal CLI (npmcu) or as an imported module (both ESM and CommonJS support).

Quick Start (CLI)

Run it instantly without installing:

npx npm-check-and-update

Or install it globally for convenience:

npm install -g npm-check-and-update

Usage

Use either the full command or the short alias (npmcu):

# Check the package.json in the current directory or nearest parent folder
npmcu

# Run from a deeply nested folder (automatically locates project root)
cd src/components/Button
npmcu

# Check a package.json at a specific location
npmcu ./some-other-project/package.json

Sample Output

Reading: /Users/you/my-app/package.json
Checking 12 package(s) for updates...

📦 Outdated packages:

  express     ^4.17.0   -> 4.19.2       (dependencies)
  lodash      ^4.17.20  -> 4.17.21      (dependencies)
  eslint      ^7.0.0    -> 9.9.0        (devDependencies)

Summary: 3 outdated, 9 up to date, 0 errored (12 total)

npm Script Integration

Add it to your project's package.json to keep dependency checks standard across your team:

npm install --save-dev npm-check-and-update

{
  "scripts": {
    "check:updates": "npmcu"
  }
}

Then run:

npm run check:updates

Programmatic API Usage

Use npm-check-and-update as a Node.js library in your custom automation scripts.

ESM (Import)

import { checkForUpdates } from 'npm-check-and-update';

async function run() {
  const result = await checkForUpdates();
  console.log(`Checked: ${result.pkgPath}`);
  console.log('Outdated Packages:', result.outdated);
}

run();

CommonJS (Require)

const { checkForUpdates } = require('npm-check-and-update');

async function run() {
  const result = await checkForUpdates('./package.json', { concurrency: 15 });
  console.log('Total packages checked:', result.total);
}

run();

API Reference

checkForUpdates(pkgPath?, options?)

Walks up from process.cwd() (or a specific pkgPath), queries the npm registry, and returns structured results.

• pkgPath (string, optional): Direct path to package.json. Defaults to finding the nearest package.json.

• options.concurrency (number, optional): Maximum concurrent HTTP requests to the npm registry. Default is 10.

{
  outdated: Array<{ name: string; current: string; latest?: string; section: string }>;
  upToDate: Array<{ name: string; current: string; latest?: string; section: string }>;
  errored:  Array<{ name: string; current: string; section: string; error?: string }>;
  total: number;
  pkgPath: string; // Absolute path to the checked package.json
}

Roadmap

• Interactive mode (--interactive / -i) to select and apply individual updates.

• Automated update execution (--update / -u) to execute write back to package.json.

• Option to toggle between strict semver range updates vs. target latest tags.

License

MIT