{"id":51118976,"url":"https://github.com/sulthonzh/npm-outdated-check","last_synced_at":"2026-06-25T00:30:35.230Z","repository":{"id":360060732,"uuid":"1248200999","full_name":"sulthonzh/npm-outdated-check","owner":"sulthonzh","description":"CI-friendly dependency version threshold checker with configurable version drift limits and meaningful exit codes","archived":false,"fork":false,"pushed_at":"2026-06-19T21:08:04.000Z","size":173,"stargazers_count":0,"open_issues_count":21,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T23:06:38.259Z","etag":null,"topics":["check","ci","dependencies","dependency","management","npm","outdated","semver","threshold","version"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sulthonzh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T10:21:38.000Z","updated_at":"2026-06-19T08:56:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sulthonzh/npm-outdated-check","commit_stats":null,"previous_names":["sulthonzh/npm-outdated-check"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/sulthonzh/npm-outdated-check","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fnpm-outdated-check","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fnpm-outdated-check/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fnpm-outdated-check/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fnpm-outdated-check/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sulthonzh","download_url":"https://codeload.github.com/sulthonzh/npm-outdated-check/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fnpm-outdated-check/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34755061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["check","ci","dependencies","dependency","management","npm","outdated","semver","threshold","version"],"created_at":"2026-06-25T00:30:35.158Z","updated_at":"2026-06-25T00:30:35.219Z","avatar_url":"https://github.com/sulthonzh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# npm-outdated-check\n\n![CI](https://github.com/sulthonzh/npm-outdated-check/workflows/CI/badge.svg)\n![npm](https://img.shields.io/npm/v/npm-outdated-check)\n![License](https://img.shields.io/npm/l/npm-outdated-check)\n\nCI-friendly dependency version threshold checker with configurable version drift limits and meaningful exit codes.\n\n## Why?\n\n`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.\n\n**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.\n\n## Features\n\n- ✅ Zero-config CI integration — just works in GitHub Actions, GitLab CI, Jenkins\n- ✅ Semantic version thresholding — configure max allowed major/minor/patch drift\n- ✅ Smart default policies — sensible defaults for different project types\n- ✅ Human-friendly output — clear warnings about policy violations\n- ✅ Multiple output formats — text, table, JSON\n- ✅ Meaningful exit codes — CI can gate builds based on results\n- ✅ Configurable — CLI options + config file support\n- ✅ TypeScript implementation\n\n## Installation\n\n```bash\nnpm install -g npm-outdated-check\n```\n\nOr as a dev dependency:\n\n```bash\nnpm install -D npm-outdated-check\n```\n\n## Usage\n\n### Basic\n\nCheck all dependencies with default thresholds (major=0, minor=2, patch=5):\n\n```bash\nnpm-outdated-check\n```\n\n### Custom thresholds\n\nFail if any dependency is more than 1 major version behind:\n\n```bash\nnpm-outdated-check --max-major 1 --max-minor 5\n```\n\n### Production only\n\nCheck only production dependencies:\n\n```bash\nnpm-outdated-check --dep prod\n```\n\n### JSON output\n\n```bash\nnpm-outdated-check --format json\n```\n\n### Markdown output (great for PR comments)\n\n```bash\nnpm-outdated-check --format markdown\n```\n\nOutput looks like:\n\n```markdown\n## Dependency Check\n\n❌ **2 violation(s)** found out of 15 dependencies.\n\n| Package | Current | Latest | Type | Major | Minor | Patch |\n|---------|---------|--------|------|-------|-------|-------|\n| react | `^18.0.0` | `19.0.0` | prod | **1** ⚠️ | 0 | 0 |\n| lodash | `^4.17.0` | `4.17.21` | prod | 0 | 0 | **21** ⚠️ |\n\n_Thresholds: major=0, minor=2, patch=5_\n```\n\n### Config file\n\nCreate `.npm-outdated-check.json` in your project root:\n\n```json\n{\n  \"maxMajor\": 0,\n  \"maxMinor\": 2,\n  \"maxPatch\": 5,\n  \"include\": [\"prod\", \"dev\"],\n  \"exclude\": [\"typescript\"],\n  \"registry\": \"https://registry.npmjs.org\",\n  \"format\": \"text\"\n}\n```\n\n## CLI Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--max-major \u003cn\u003e` | 0 | Maximum major version drift |\n| `--max-minor \u003cn\u003e` | 2 | Maximum minor version drift |\n| `--max-patch \u003cn\u003e` | 5 | Maximum patch version drift |\n| `--dep \u003ctypes\u003e` | both | Include dependencies (prod, dev, both) |\n| `--exclude \u003cpkgs\u003e` | - | Exclude packages (comma-separated) |\n| `--registry \u003curl\u003e` | https://registry.npmjs.org | npm registry URL |\n| `--format \u003cfmt\u003e` | text | Output format (text, table, json, markdown) |\n| `--config \u003cpath\u003e` | - | Path to config file |\n| `--path \u003cdir\u003e` | cwd | Project directory |\n| `--verbose` | false | Verbose output |\n| `--fail-on-any` | true | Exit with code 1 if any violations found (set to false for report-only mode) |\n\n## Exit Codes\n\n- `0`: No violations found — build passes\n- `1`: Violations found — dependencies exceed thresholds\n- `2`: Configuration errors\n- `3`: Network/registry errors\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Error: Registry hostname not allowed for security\"**\n- This is a security feature that restricts registry URLs to known safe domains\n- Use official npm registry: `https://registry.npmjs.org`\n- For private registries, make sure they're on a trusted domain\n\n**\"Configuration errors\" exit code 2**\n- Check your `.npm-outdated-check.json` for invalid JSON format\n- Verify registry URLs are properly formatted\n- Ensure exclude patterns are valid npm package names\n\n**\"Network/registry errors\" exit code 3**\n- Check your internet connection\n- Verify the registry URL is accessible\n- Use `--verbose` flag for more detailed error information\n- Private registries may require authentication (not currently supported)\n\n### Performance Tips\n\n- Enable caching by default (1-hour TTL) for faster repeated checks\n- Use `--exclude` patterns to skip known stable packages\n- For large projects, the `--transitive` flag may increase check time\n- Use `--disable-cache` only when you need absolute latest version data\n\n## CI Examples\n\n### GitHub Actions\n\n```yaml\nname: Dependency Check\n\non: [push, pull_request]\n\njobs:\n  outdated-check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '18'\n      - run: npm install\n      - run: npx npm-outdated-check --max-minor 3\n```\n\n### GitLab CI\n\n```yaml\ndependency-check:\n  stage: test\n  script:\n    - npm install\n    - npx npm-outdated-check --max-major 0 --max-minor 2\n```\n\n### Jenkins\n\n```groovy\nstage('Dependency Check') {\n  steps {\n    sh 'npm install'\n    sh 'npx npm-outdated-check --dep prod --max-minor 2 || exit 1'\n  }\n}\n```\n\n## Library Usage\n\n```typescript\nimport { OutdatedChecker, Formatter, ConfigLoader } from 'npm-outdated-check';\n\nconst config = await ConfigLoader.load();\nconst checker = new OutdatedChecker(config);\nconst { violations } = await checker.check();\n\nconst formatter = new Formatter(config);\nconsole.log(formatter.format({ violations, totalChecked: 10, passed: true, config }));\n\nconst exitCode = checker.getExitCode(violations);\nprocess.exit(exitCode);\n```\n\n## Configuration File\n\nPlace `.npm-outdated-check.json` in your project root:\n\n```json\n{\n  \"maxMajor\": 0,\n  \"maxMinor\": 2,\n  \"maxPatch\": 5,\n  \"include\": [\"prod\", \"dev\"],\n  \"exclude\": [\"@types/*\"],\n  \"registry\": \"https://registry.npmjs.org\",\n  \"format\": \"table\"\n}\n```\n\n## Comparison\n\n| Feature | `npm-outdated-check` | `npm outdated` | `npm-check-updates` | `depcheck` | `renovate` |\n|---------|---------------------|----------------|---------------------|-----------|------------|\n| Version drift thresholds | ✅ Configurable per major/minor/patch | ❌ | ❌ | ❌ | ✅ (but complex) |\n| CI exit codes | ✅ Meaningful (0–3) | ✅ (0/1 only) | ❌ | ✅ | ❌ |\n| Config file | ✅ `.npm-outdated-check.json` | ❌ | ✅ | ✅ | ✅ (`renovate.json`) |\n| Output formats | Text, table, JSON, markdown | Text only | Text, JSON | Text, JSON | Dashboard |\n| Markdown for PR comments | ✅ Built-in | ❌ | ❌ | ❌ | ✅ (via bot) |\n| Exclude patterns | ✅ Globs (`@types/*`) | ❌ | ✅ | ✅ | ✅ |\n| Registry caching | ✅ Built-in | ❌ | ❌ | N/A | ✅ |\n| Setup time | \u003c2 min | 0 min | \u003c2 min | \u003c2 min | 30+ min |\n| Use case | CI threshold gate | Quick manual check | Bulk update | Find unused deps | Auto-merge PRs |\n\n## Contributing\n\nContributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## License\n\nMIT © [Sulthon](https://github.com/sulthonzh)\n\n## Related\n\n- [npm-check-updates](https://github.com/raineorshine/npm-check-updates) — updates package.json dependencies\n- [npm outdated](https://docs.npmjs.com/cli/v10/commands/npm-outdated) — built-in outdated check\n- [depcheck](https://github.com/depcheck/depcheck) — checks for unused dependencies","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsulthonzh%2Fnpm-outdated-check","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsulthonzh%2Fnpm-outdated-check","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsulthonzh%2Fnpm-outdated-check/lists"}