NPM Package Conflict Checker

A TypeScript-based tool to detect and report dependency conflicts in NPM packages. Identifies peer dependency mismatches, version range conflicts, and Node.js engine incompatibilities across your entire dependency tree.

Features

• Peer Dependency Conflict Detection - Identifies when installed packages don't satisfy peer dependency requirements
• Version Range Conflict Detection - Finds incompatible version ranges across the dependency tree
• Node Engine Conflict Detection - Checks if packages require different Node.js versions than currently running
• Multiple Input Methods - File path, stdin, or direct package specifications
• Transitive Analysis - Analyzes both direct and nested dependencies
• Human-Readable Suggestions - Provides actionable recommendations to resolve conflicts
• Strict TypeScript - Fully typed with zero any types
• Fast & Concurrent - Uses pacote with concurrency control and in-memory caching

Installation

# Using pnpm
pnpm add npm-conflict-checker

# Using npm
npm install npm-conflict-checker

# Using yarn
yarn add npm-conflict-checker

CLI Usage

1. Check a package.json file

npx npm-conflict-check ./package.json

2. Read from stdin

cat package.json | npx npm-conflict-check

3. Check specific packages

npx npm-conflict-check react@18 react-dom@18 @types/react@17

CLI Options

• --json - Output raw JSON format
• --pretty - Output formatted console output (default)

Exit Codes

• 0 - No conflicts detected
• 1 - Conflicts found
• 2 - Runtime error

Programmatic API

Basic Usage

import { checkConflicts } from 'npm-conflict-checker';

// Check conflicts from package.json object
const packageJson = {
  dependencies: {
    react: '^18.0.0',
    'some-lib': '^1.0.0'
  }
};

const report = await checkConflicts(packageJson);

if (report.hasConflict) {
  console.log(`Found ${report.conflicts.length} conflicts`);
  report.conflicts.forEach(conflict => {
    console.log(`${conflict.type}: ${conflict.package}`);
    console.log(`Suggestion: ${conflict.suggestion}`);
  });
}

Using PackageInput Array

import { checkConflicts } from 'npm-conflict-checker';

const packages = [
  { name: 'react', version: '^18.0.0' },
  { name: 'vue', version: '^3.0.0' }
];

const report = await checkConflicts(packages);

With Options

import { checkConflicts } from 'npm-conflict-checker';

const report = await checkConflicts(packages, {
  concurrency: 10 // Max concurrent registry requests
});

API Reference

checkConflicts(input, options?)

Main function to check for conflicts.

Parameters:

• input: PackageInput[] | Record<string, unknown> - Array of packages or package.json object
• options?: ConflictCheckOptions - Optional configuration

Returns: Promise<ConflictReport>

Types

interface PackageInput {
  name: string;
  version: string;
}

interface ConflictResult {
  type: 'peer' | 'version' | 'engine';
  package: string;
  required: string;
  found: string;
  introducedBy: string;
  suggestion: string;
}

interface ConflictReport {
  hasConflict: boolean;
  conflicts: ConflictResult[];
}

interface ConflictCheckOptions {
  concurrency?: number; // Default: 5
}

Conflict Types

Peer Dependency Conflicts

Detected when an installed package version doesn't satisfy a peer dependency requirement.

Example:

{
  "type": "peer",
  "package": "react",
  "required": "^17.0.0",
  "found": "18.2.0",
  "introducedBy": "some-lib",
  "suggestion": "Update some-lib to support [email protected] or install react@^17.0.0"
}

Version Range Conflicts

Detected when multiple packages require incompatible version ranges of the same dependency.

Example:

{
  "type": "version",
  "package": "lodash",
  "required": "^4.17.0 (by lib-a), ^3.10.0 (by lib-b)",
  "found": "4.17.21, 3.10.1",
  "introducedBy": "lib-a, lib-b",
  "suggestion": "Update lib-a or lib-b to use compatible version ranges of lodash"
}

Node Engine Conflicts

Detected when a package requires a different Node.js version than currently running.

Example:

{
  "type": "engine",
  "package": "some-package",
  "required": ">=18.0.0",
  "found": "v16.14.0",
  "introducedBy": "root",
  "suggestion": "Upgrade Node.js to >=18.0.0 or remove some-package"
}

Output Examples

Pretty Format (Default)

📦 NPM Package Conflict Checker

❌ Found 2 conflict(s):

🔗 PEER CONFLICT
   Package: react
   Required: ^17.0.0
   Found: 18.2.0
   Introduced by: some-lib
   💡 Update some-lib to support [email protected] or install react@^17.0.0

⚙️ ENGINE CONFLICT
   Package: old-package
   Required: >=14.0.0
   Found: v18.0.0
   Introduced by: root
   💡 Upgrade Node.js to >=14.0.0 or remove old-package

JSON Format

npx npm-conflict-check ./package.json --json

{
  "hasConflict": true,
  "conflicts": [
    {
      "type": "peer",
      "package": "react",
      "required": "^17.0.0",
      "found": "18.2.0",
      "introducedBy": "some-lib",
      "suggestion": "Update some-lib to support [email protected] or install react@^17.0.0"
    }
  ]
}

How It Works

1. Resolution - Fetches package manifests from NPM registry using pacote
2. Graph Building - Constructs a complete dependency graph including transitive dependencies
3. Conflict Detection - Applies three detection rules:
   • Peer dependency validation
   • Version range compatibility checking
   • Node engine version validation
4. Reporting - Returns structured conflict report with actionable suggestions

Development

Build

pnpm install
pnpm build

Project Structure

src/
├── index.ts                    # Public API exports
├── core/
│   ├── types.ts               # Type definitions
│   ├── resolver.ts            # Package resolution with pacote
│   ├── conflict-detector.ts   # Conflict detection rules
│   └── engine.ts              # Main orchestration
└── cli/
    └── index.ts               # CLI implementation

Tech Stack

• Language: TypeScript (strict mode)
• Runtime: Node.js ≥ 18
• Package Manager: pnpm
• Dependencies:
  • pacote - Package manifest fetching
  • semver - Semantic version parsing
  • npm-package-arg - Package specifier parsing
  • p-limit - Concurrency control
  • commander - CLI framework

Contributing

Contributions are welcome! Please ensure:

• All code passes TypeScript strict mode checks
• No any types are introduced
• Tests are added for new features
• Code follows existing patterns and style

License

MIT

Related Projects

• npm
• pacote
• semver

Made with TypeScript and strict typing discipline.