npmlens

Know everything about an npm package before you install it.

You find a package with 10K stars. You npm install it. Turns out it pulls 87 sub-dependencies, hasn't been updated in a year, runs a sketchy postinstall script, and the maintainer abandoned it.

npmlens gives you the full picture before you commit.

Install

npm install -g npmlens

Or run it directly without installing:

npx npmlens <package-name>

Usage

# Full analysis
npx npmlens express

# Analyze a specific version
npx npmlens [email protected]

# Scoped packages work too
npx npmlens @babel/core

# Compare packages side by side
npx npmlens compare axios got node-fetch

# CI gate: fail the build if health score < 70
npx npmlens express --fail-under 70

# Skip dependency tree (faster)
npx npmlens lodash --no-tree

# Skip alternative suggestions
npx npmlens react --no-alternatives

# JSON output (for scripts and CI)
npx npmlens axios --json

# Deeper dependency tree
npx npmlens webpack --depth 5

What You Get

• Health Score (0-100) — Weighted composite across 5 categories
• Maintenance — Publish frequency, last update, version history
• Security — Known CVEs via OSV.dev with real CVSS severity scoring, plus install-script detection
• Supply Chain — npm provenance attestation, preinstall/postinstall script warnings
• Dependencies — Direct + transitive count, full dependency tree visualization
• Community — GitHub stars, issue close ratio, last commit, archived status
• Bundle Size — Minified + gzipped size, tree-shakeability, side effects
• Module Info — TypeScript types, ESM/CJS format, Node engine range, install size
• Download Trends — Weekly/monthly/yearly stats with sparkline chart
• Alternatives — Similar packages ranked by quality, popularity, and maintenance
• Compare — Side-by-side comparison of 2-4 packages
• Verdict — Clear recommendation based on overall health

Example Output

  HEALTH SCORE
  ███████████████████████████░░░ 90/100

  ⚠  WARNINGS
    • 28 direct dependencies — very heavy

  ✓  POSITIVES
    • Recently published
    • No known vulnerabilities
    • Published with provenance attestation
    • Ships TypeScript types
    • 97.2% issues closed

  VERDICT
  ✓ This package looks healthy. Safe to install.

Compare Mode

  ⚖ npmlens compare: axios vs got vs node-fetch

   Health Score │ 90/100   │ 84/100   │ 62/100
   Weekly DLs   │ 113.2M   │ 35.1M    │ 148.1M
   Gzipped      │ 15.8 KB  │ 44.2 KB  │ 22.6 KB
   ...

  VERDICT
  ✓ axios has the highest health score (90/100).

Commands & Options

| Command / Flag | Description | |-----------------------|---------------------------------------------------| | npmlens <pkg> | Analyze a package (supports pkg@version) | | npmlens compare <a> <b> [...] | Compare 2-4 packages side by side | | --no-tree | Skip dependency tree analysis | | --no-alternatives | Skip alternative package suggestions | | --depth <n> | Dependency tree depth, 1-6 (default: 3) | | --json | Output raw JSON | | --fail-under <score>| Exit with code 1 if health score is below <score> — perfect for CI |

Use in CI

Gate your dependency PRs on package health:

# GitHub Actions example
- name: Check dependency health
  run: npx npmlens some-new-dependency --no-tree --no-alternatives --fail-under 60

GitHub Token

To avoid GitHub API rate limits (60 req/hr), set a personal access token:

export GITHUB_TOKEN=ghp_your_token_here

Requirements

Node.js >= 18

License

MIT

Author

imsurajchahar

Contributing

Issues and PRs welcome at github.com/iamsurajchahar/npmlens.