A dependency check tool for monorepos
npm install monodepworkspace:* protocol and are properly referenced.
--only-extras for wrongType, mismatch, outdated, internal, and peer checks
package.json workspaces or pnpm-workspace.yaml.
package.json but not imported in the code.
package.json.
devDependencies but are in dependencies (or vice versa).
workspace:* protocol or unlisted internal imports.
bash
npm install -g monodep
`
Or use directly via npx:
`bash
npx monodep
`
$3
1. Clone the repository.
2. Install dependencies:
`bash
npm install
`
3. Build the project:
`bash
npm run build
`
4. Link globally (optional):
`bash
npm link
`
Usage
$3
Run the tool against your project root:
`bash
npx monodep /path/to/your/project
`
Or in the current directory:
`bash
npx monodep .
`
$3
| Option | Description |
|--------|-------------|
| --compact | Output compact log format for AI agents and CI pipelines |
| --only-extras | Only run checks not covered by Knip (wrongType, mismatch, outdated, internal, peer) |
| --no-outdated | Skip outdated dependency checks for faster execution |
$3
`text
📦 monodep - Monorepo Dependency Checker
Analyzing project at /path/to/project...
Found 3 packages.
📁 package-a
/path/to/project/packages/a
⚠ Unused dependencies:
- lodash
✗ Missing dependencies:
- react
⚡ Wrong dependency types:
- chalk: Should be in devDependencies (found in dependencies)
⏰ Outdated dependencies:
- typescript: ^5.0.0 → 5.3.3
🔗 Internal package issues:
- @myorg/utils: Should use workspace:* protocol
👥 Peer dependency issues:
- react: Missing peer dependency (required by @myorg/ui)
📁 package-b
/path/to/project/packages/b
✓ No issues found.
🔀 Version Mismatches Found:
lodash:
- ^4.17.21 in package-a, package-c
- ^4.17.20 in package-b
──────────────────────────────────────────────────
📊 Summary
Packages scanned: 3
Packages with issues: 1
⚠ Unused: 1
✗ Missing: 1
⚡ Wrong type: 1
⏰ Outdated: 1
🔀 Mismatches: 1
🔗 Internal: 1
👥 Peer: 1
──────────────────────────────────────────────────
❌ Total issues: 7
`
$3
For CI pipelines or AI agents, use the --compact flag:
`bash
npx monodep . --compact
`
Output:
`text
[monodep] scanned=3 issues=7
[unused] package-a: lodash
[missing] package-a: react
[wrongType] package-a: chalk (dependencies -> devDependencies)
[outdated] package-a: typescript (^5.0.0 -> 5.3.3)
[mismatch] *: lodash (^4.17.21(package-a,package-c) vs ^4.17.20(package-b))
[internal] package-a: @myorg/utils (should use workspace:*)
[peer] package-a: react (missing, required by @myorg/ui)
`
Knip Integration Mode
If you're already using Knip for unused dependency detection, you can run monodep in --only-extras mode to avoid duplicate checks:
`bash
Run only monodep-specific checks
npx monodep . --only-extras
Combine with compact output for CI
npx monodep . --only-extras --compact
`
This mode skips unused/missing dependency detection (which Knip handles) and focuses on:
- wrongType: Dependencies in wrong section (devDependencies vs dependencies)
- mismatch: Version inconsistencies across packages
- outdated: Packages with newer versions available
- internal: Internal workspace package reference issues
- peer: Peer dependency validation issues
Configuration
Create a configuration file in your project root. Supported formats:
- .monodeprc
- .monodeprc.json
- .monodeprc.yaml
- .monodeprc.yml
- .monodeprc.js
- .monodeprc.cjs
- monodep.config.js
- monodep.config.cjs
$3
`json
{
"ignorePatterns": ["/generated/", "/fixtures/"],
"ignoreDependencies": ["some-optional-peer-dep"],
"skipPackages": ["@myorg/internal-tools"],
"checkOutdated": true
}
`
| Option | Type | Description |
|--------|------|-------------|
| ignorePatterns | string[] | Glob patterns for files/directories to ignore during scanning |
| ignoreDependencies | string[] | Dependencies to exclude from unused/missing checks |
| skipPackages | string[] | Package names to skip entirely |
| checkOutdated | boolean | Enable/disable outdated dependency checking (default: true) |
How it Works
1. Monorepo Detection: It looks for workspaces in package.json or packages in pnpm-workspace.yaml to identify all packages in the monorepo.
2. File Scanning: For each package, it scans for source files (.ts, .tsx, .js, .jsx, .mjs, .cjs), excluding node_modules, dist, build, and nested sub-packages.
3. Import Parsing: It parses the source files using TypeScript's parser to find all import statements.
4. Dependency Comparison: It compares the found imports against the dependencies, devDependencies, and peerDependencies listed in the package's package.json.
5. Type Classification: It detects whether imports are used in production code or test files to identify wrong dependency types.
6. Version Checking: It queries the npm registry to find the latest versions of dependencies. Optimized with deduplication, caching, and parallel requests (max 10 concurrent) to minimize registry load.
7. Consistency Check: It compares dependency versions across all packages to find mismatches.
Performance
The outdated dependency check requires network requests to the npm registry. To optimize performance:
- Deduplication: Same packages across multiple workspaces are only checked once
- Parallel requests: Up to 10 concurrent requests with rate limiting
- Caching: Version information is cached during execution
- Skip option: Use --no-outdated to skip version checks entirely for fastest execution
`bash
Fast mode (skip outdated checks)
npx monodep . --no-outdated
Full check with outdated detection
npx monodep .
`
Exit Codes
| Code | Description |
|------|-------------|
| 0 | No issues found |
| 1` | One or more issues detected |