monorepo-dep-checker/README.md

monorepo-dep-checker

A powerful CLI tool for managing and checking dependencies across packages in a monorepo. Helps you identify version mismatches, missing dependencies, and maintain consistency across your workspace packages.

Features

• 🔍 Check for version differences across packages
• ⚠️ Identify missing dependencies between your main app and packages
• 🔄 Update dependencies to the highest compatible version
• 🏗️ Full workspace package support
• 📊 Clear, actionable summaries
• 🚦 CI gating via exit codes (--fail-on-diff, --fail-on-missing)
• 🚀 Fast, zero-config setup

Installation

# Global installation
npm install -g @warkypublic/monorepo-dep-checker

# Or locally in your project
npm install --save-dev @warkypublic/monorepo-dep-checker

Quick Start

Basic usage with default paths (assumes ./package.json for main app and ./packages for workspace packages):

dep-check

Usage Examples

1. Check Version Differences

Find packages using different versions of the same dependency:

dep-check --check-versions

# Output example:
react:
  Difference (major):
    ^17.0.2 vs ^18.0.0

    Packages using ^17.0.2:
      - my-app (package.json)
      - components (packages/components/package.json)

    Packages using ^18.0.0:
      - new-feature (packages/new-feature/package.json)

    Recommended action:
    ⚠️  Major version difference - Manual review recommended

2. Check Missing Dependencies

Find dependencies that exist in packages but are missing from the main app:

dep-check --check-missing

# Output example:
Summary:
Packages with dependency mismatches: 2
Unique dependencies missing from main app: 1
  lodash
Unique unused dependencies from main app: 1
  axios

3. Update Dependencies

Update all dependencies to their highest compatible version:

# Dry run - show what would be updated
dep-check --update --dry-run

# Actually perform the updates
dep-check --update

4. Custom Paths

Specify custom paths for your main app and packages:

dep-check --app ../my-app/package.json --packages ../my-app/packages

5. JSON Output

Get results in JSON format for further processing:

dep-check --check-versions --format json

6. CI Gating

Exit with code 1 when the check finds a problem, so a pipeline fails:

# Fail if any dependency resolves to more than one version
dep-check --check-versions --fail-on-diff

# Fail if any package depends on something the main app does not declare
dep-check --check-missing --fail-on-missing

# Both gates in one run
dep-check --fail-on-diff --fail-on-missing

Exit code	Meaning
0	No gate was tripped
1	A gate was tripped, or the run errored

Notes:

• A gate runs whatever analysis it needs, even outside its own mode — --check-missing --fail-on-diff still detects version conflicts.
• Failure messages go to stderr, so --format json keeps stdout parseable.
• Gates cannot be combined with --update: --update rewrites the tree mid-run, which would leave the exit code describing a state that no longer exists.

Command Line Options

Options:
  --app, -a          Path to main app package.json [default: "./package.json"]
  --packages, -p     Path to packages directory [default: "./packages"]
  --update, -u       Update dependencies to highest compatible version
  --dry-run, -d      Show what would be updated without making changes
  --check-versions   Check for version differences between packages
  --check-missing    Check for dependencies missing between app and packages
  --format, -f       Output format (text or json) [default: "text"]
  --strict, -s       Only update range deps (~, ^, >=) when they are incompatible
  --fail-on-diff     Exit 1 if any dependency resolves to more than one version
  --fail-on-missing  Exit 1 if a package depends on something the main app does not
  --help, -h         Show help
  --version, -V      Show version number

Features

Workspace Support

• Automatically detects and handles workspace dependencies
• Ignores workspace:* protocol dependencies
• Properly manages workspace package references
• Supports npm, yarn, and pnpm workspaces

Version Analysis

• Identifies major, minor, and patch version differences
• Provides clear upgrade recommendations
• Shows detailed package locations
• Helps prevent dependency conflicts

Missing Dependency Detection

• Finds dependencies used in packages but missing from main app
• Identifies unused main app dependencies
• Shows unique missing dependencies to avoid duplication
• Excludes workspace packages from analysis

Best Practices

1. Run --check-versions before updates to identify potential breaking changes
2. Use --dry-run before applying updates
3. Review major version differences manually
4. Keep workspace dependencies consistent across packages
5. Gate CI with --check-versions --fail-on-diff so drift cannot merge

Development

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm lint        # eslint ./src
pnpm test        # vitest
pnpm build       # vite build -> dist/

Contributing

Contributions are welcome! Please read our contributing guidelines for details.

License

MIT License - see LICENSE file for details