NPM check deprecations

npm-check-deprecations finds deprecated packages anywhere in your lockfile dependency tree and shows the chains that pull them in.

This package ships a native Rust core via NAPI-RS as part of the riri-node-tools monorepo.

Table of Contents

• Prerequisites
• Installation
• Usage
  • CLI
  • Node API
• Options
• Workspace mode
• Debug

Prerequisites

• Node.js version ^22.22.2 || ^24.15.0 || >=26.0.0

Supported platforms:

| OS | Arch | | ------- | -------------------------------------- | | Linux | x64 (glibc, musl), arm64 (glibc, musl) | | macOS | x64, arm64 | | Windows | x64 |

Installation

Install globally:

npm install -g @smarlhens/npm-check-deprecations

Or run with npx:

npx @smarlhens/npm-check-deprecations

Usage

CLI

Find deprecated packages in the dependency tree and print the chains that reach them:

ncd

Sample output (against fixtures/ncd-npm-deprecated-demo):

ncd-demo
├─ [email protected]  ⛔ blocks: requires fake-legacy@~0.2.0, fix needs 0.3.0 → fake-app update required  (latest: 3.1.0)
│  └─ [email protected]  ⚠ deprecated: fake-legacy is unmaintained; migrate to fake-modern  (latest: 0.3.0)
├─ [email protected] (dev)  ⛔ blocks: requires fake-legacy@^0.2.0, fix needs 0.3.0 → fake-test update required  (latest: 4.0.0)
│  └─ [email protected]  ⚠ deprecated: fake-legacy is unmaintained; migrate to fake-modern (see above)
└─ [email protected]  (fix: update fake-util — ^1.0.0 allows 1.4.0)  ⚠ deprecated: fake-util is deprecated in favor of @demo/fake-util  (latest: 2.0.0)


  2 deprecated package(s) found

Each deprecated package is annotated with its registry deprecation message and the newest non-deprecated version. When a parent's declared range blocks the fix, the parent edge is flagged as a blocker.

Emit machine-readable JSON:

ncd --json

Override the registry (defaults to .npmrc, then the public npm registry):

ncd --registry https://registry.npmjs.org

Supports package-lock.json (v1/v2/v3), yarn.lock (classic & berry), and pnpm-lock.yaml (v5/v6/v9), auto-detected.

Exit codes: 0 no deprecated packages · 1 deprecated packages found · 2 runtime error.

Node API

import { checkDeprecations } from '@smarlhens/npm-check-deprecations';

const packageJson = '...'; // stringified package.json
const lockfileContent = '...'; // stringified lockfile

// Fetches packuments from the registry (blocking I/O).
const { tree, deprecated } = checkDeprecations({
  packageJson,
  lockfileContent,
  lockfileType: 'npm', // optional: 'npm' | 'yarn' | 'pnpm' (defaults to 'npm')
  // registry: 'https://registry.npmjs.org', // optional registry override
});

for (const pkg of deprecated) {
  console.log(`${pkg.name}@${pkg.version}: ${pkg.message ?? 'deprecated'}`);
}

if (tree) {
  console.log(tree); // the same chains the CLI prints
}

runCli(argv) is also exported to run the ncd CLI in-process; argv[0] must be the program name. Returns the exit code.

Options

Core logic for npm-check-deprecations

Usage: ncd [OPTIONS]

Options:
  -q, --quiet                Silent mode — no progress output
  -v, --verbose              Verbose output
  -d, --debug                Debug mode — detailed logging
      --json                 Output results as JSON
      --registry <REGISTRY>  Registry URL override (default: .npmrc, then <https://registry.npmjs.org>)
  -h, --help                 Print help
  -V, --version              Print version

Workspace mode

When run from the root of an npm, pnpm, or yarn workspace, ncd auto-detects the workspace and analyzes each member's dependency tree against the shared root lockfile. Output is grouped per member; only members that pull in a deprecated package are shown.

Debug

ncd -d

The -d/--debug flag enables detailed logging to stderr. No environment variable is required.

  ▸ Detecting lockfile......
  ✓ Detected package-lock.json
  ▸ Reading package.json......
  ✓ Read package.json
  ▸ Building dependency graph......
  ✓ Built dependency graph
  ▸ Checking 4 packages against registry......
  ✓ Checked packages against registry
ncd-demo
├─ [email protected]  ⛔ blocks: requires fake-legacy@~0.2.0, fix needs 0.3.0 → fake-app update required  (latest: 3.1.0)
│  └─ [email protected]  ⚠ deprecated: fake-legacy is unmaintained; migrate to fake-modern  (latest: 0.3.0)
├─ [email protected] (dev)  ⛔ blocks: requires fake-legacy@^0.2.0, fix needs 0.3.0 → fake-test update required  (latest: 4.0.0)
│  └─ [email protected]  ⚠ deprecated: fake-legacy is unmaintained; migrate to fake-modern (see above)
└─ [email protected]  (fix: update fake-util — ^1.0.0 allows 1.4.0)  ⚠ deprecated: fake-util is deprecated in favor of @demo/fake-util  (latest: 2.0.0)


  2 deprecated package(s) found