npm-outdated-check

CI-friendly dependency version threshold checker with configurable version drift limits and meaningful exit codes.

Why?

npm outdated has no exit codes or version threshold configuration. You can't automatically fail CI builds when dependencies drift too far from their intended versions.

Example scenario: Your team wants to ensure no production dependency is more than 2 minor versions behind the latest, to avoid unexpected breaking changes while staying current with security patches.

Features

• ✅ Zero-config CI integration — just works in GitHub Actions, GitLab CI, Jenkins
• ✅ Semantic version thresholding — configure max allowed major/minor/patch drift
• ✅ Smart default policies — sensible defaults for different project types
• ✅ Human-friendly output — clear warnings about policy violations
• ✅ Multiple output formats — text, table, JSON
• ✅ Meaningful exit codes — CI can gate builds based on results
• ✅ Configurable — CLI options + config file support
• ✅ TypeScript implementation
• ✅ Security vulnerability scanning — optional security audit for dependencies
• ✅ GitHub release automation — automated releases on version tags

Installation

npm install -g npm-outdated-check

Or as a dev dependency:

npm install -D npm-outdated-check

Usage

Basic

Check all dependencies with default thresholds (major=0, minor=2, patch=5):

npm-outdated-check

Custom thresholds

Fail if any dependency is more than 1 major version behind:

npm-outdated-check --max-major 1 --max-minor 5

Production only

Check only production dependencies:

npm-outdated-check --dep prod

JSON output

npm-outdated-check --format json

Config file

Create .npm-outdated-check.json in your project root:

{
  "maxMajor": 0,
  "maxMinor": 2,
  "maxPatch": 5,
  "include": ["prod", "dev"],
  "exclude": ["typescript"],
  "registry": "https://registry.npmjs.org",
  "format": "text"
}

CLI Options

| Option | Default | Description | |--------|---------|-------------| | --max-major <n> | 0 | Maximum major version drift | | --max-minor <n> | 2 | Maximum minor version drift | | --max-patch <n> | 5 | Maximum patch version drift | | --dep <types> | both | Include dependencies (prod, dev, both) | | --exclude <pkgs> | - | Exclude packages (comma-separated) | | --registry <url> | https://registry.npmjs.org | npm registry URL | | --format <fmt> | text | Output format (text, table, json) | | --config <path> | - | Path to config file | | --path <dir> | cwd | Project directory | | --verbose | false | Verbose output | | --security-scan | false | Include security vulnerability scanning |

Exit Codes

• 0: No violations found — build passes
• 1: Violations found — dependencies exceed thresholds
• 2: Configuration errors
• 3: Network/registry errors

CI Examples

GitHub Actions

name: Dependency Check

on: [push, pull_request]

jobs:
  outdated-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm install
      - run: npx npm-outdated-check --max-minor 3

GitLab CI

dependency-check:
  stage: test
  script:
    - npm install
    - npx npm-outdated-check --max-major 0 --max-minor 2

Jenkins

stage('Dependency Check') {
  steps {
    sh 'npm install'
    sh 'npx npm-outdated-check --dep prod --max-minor 2 || exit 1'
  }
}

Security Scanning

Check for security vulnerabilities in dependencies:

# Basic security scan
npx npm-outdated-check --security-scan

# Security scan with version thresholds
npx npm-outdated-check --security-scan --max-minor 1

# Production-only security scan
npx npm-outdated-check --dep prod --security-scan

Library Usage

import { OutdatedChecker, Formatter, ConfigLoader } from 'npm-outdated-check';

const config = await ConfigLoader.load();
const checker = new OutdatedChecker(config);
const { violations } = await checker.check();

const formatter = new Formatter(config);
console.log(formatter.format({ violations, totalChecked: 10, passed: true, config }));

const exitCode = checker.getExitCode(violations);
process.exit(exitCode);

Configuration File

Place .npm-outdated-check.json in your project root:

{
  "maxMajor": 0,
  "maxMinor": 2,
  "maxPatch": 5,
  "include": ["prod", "dev"],
  "exclude": ["@types/*"],
  "registry": "https://registry.npmjs.org",
  "format": "table"
}

Contributing

Contributions welcome! Please read CONTRIBUTING.md for details.

License

MIT © Sulthon

Related

• npm-check-updates — updates package.json dependencies
• npm outdated — built-in outdated check
• depcheck — checks for unused dependencies