🔍 pkg-detective

Stop guessing. Start picking. The 30-second npm package research you wish you had.

The Problem

Every developer has wasted hours on this:

"Should I use zod or yup? Is moment still safe? Why does my project have both axios and node-fetch?"

npm search shows popularity. Google shows 3-year-old blog posts. Neither tells you what to actually pick today.

pkg-detective fixes this. One command. Live data. Clear verdict.

Quick Start

No install needed:

npx pkg-detective auth

Or install globally for faster runs:

npm install -g pkg-detective

Commands

Browse a category

npx pkg-detective auth        # Authentication libraries
npx pkg-detective orm         # ORMs & query builders
npx pkg-detective validation  # Schema validation
npx pkg-detective http        # HTTP clients
npx pkg-detective date        # Date & time utilities
npx pkg-detective testing     # Test runners & tools
npx pkg-detective logging     # Logging libraries
npx pkg-detective state       # React state management
npx pkg-detective css         # CSS / Styling solutions

Returns a ranked list scored by live health signals — not just download counts.

Compare packages side by side

npx pkg-detective compare zod yup valibot
npx pkg-detective compare better-auth next-auth lucia
npx pkg-detective compare prisma drizzle-orm typeorm

Supports up to 5 packages at once. Shows health score, downloads, stars, bundle size, TypeScript support, and a final verdict.

Get a verdict for any package

npx pkg-detective verdict moment
npx pkg-detective verdict passport
npx pkg-detective verdict zod

Answers: "Should I still use this?" Shows a full health report with scored signals and "Pick if / Avoid if" guidance.

Scan your project

Run from your project root:

cd my-app
npx pkg-detective scan

Flags:

• Deprecated packages (marked on npm)
• Archived GitHub repositories
• Legacy packages with better modern alternatives
• Duplicate-purpose packages (e.g. axios + got + node-fetch together)
• Low health score packages

List all categories

npx pkg-detective categories

How Scoring Works

Each package receives a Health Score from 0–100 built from four signals:

| Signal | Weight | How it's measured | | --- | --- | --- | | Recency | 35 pts | Days since last npm publish | | Community | 25 pts | GitHub stars | | Issue Health | 20 pts | Open issues relative to stars | | Activity | 20 pts | Releases in last 90 / 180 days |

Verdict Labels

| Label | Meaning | | --- | --- | | ✅ EXCELLENT | Health ≥ 75 — actively maintained, widely adopted | | ✅ HEALTHY | Health ≥ 55 — good shape, regular activity | | ⚠️ MODERATE | Health ≥ 35 — usable, watch for updates | | ⚠️ RISKY | Health < 35 — stale or low community signal | | 💀 ABANDONED | No releases in 2+ years | | 🗄️ ARCHIVED | GitHub repository is archived | | 🚫 DEPRECATED | Marked deprecated on npm |

Data sources:

• npm registry API — downloads, versions, publish dates
• GitHub API — stars, open issues, releases, archived status
• Bundlephobia API — gzip bundle size

Supported Categories

| Category | Command key | Packages included | | --- | --- | --- | | Authentication | auth | better-auth, next-auth, lucia, passport, jose, jsonwebtoken | | ORM / Database | orm | prisma, drizzle-orm, typeorm, sequelize, mongoose, knex | | Validation | validation | zod, yup, joi, valibot, ajv, superstruct | | HTTP Client | http | axios, got, ky, node-fetch, undici, superagent | | Date / Time | date | dayjs, date-fns, luxon, moment, @formkit/tempo | | Testing | testing | vitest, jest, mocha, @testing-library/react, playwright, cypress | | Logging | logging | pino, winston, bunyan, morgan, signale | | State (React) | state | zustand, jotai, valtio, redux, @reduxjs/toolkit, recoil | | CSS / Styling | css | tailwindcss, styled-components, @emotion/react, clsx, stitches |

Optional: GitHub Token

Without a token, GitHub API is limited to 60 requests/hour. For heavy use:

# Windows (PowerShell)
$env:GITHUB_TOKEN="your_token_here"

# macOS / Linux
export GITHUB_TOKEN=your_token_here

Create a token at github.com/settings/tokens — no scopes needed for public repos.

Project Structure

pkg-detective/
├── bin/
│   └── pkg-detective.js        ← CLI entry point
├── src/
│   ├── cli.js                  ← Commander routes
│   ├── commands/
│   │   ├── search.js           ← Category search command
│   │   ├── compare.js          ← Side-by-side comparison
│   │   ├── verdict.js          ← Single package health report
│   │   └── scan.js             ← Project audit
│   ├── data/
│   │   └── categories.js       ← Curated package lists per category
│   ├── fetchers/
│   │   ├── http.js             ← Zero-dependency HTTP client
│   │   ├── npm.js              ← npm registry + downloads API
│   │   ├── github.js           ← GitHub stars, issues, releases
│   │   └── bundlephobia.js     ← Bundle size fetcher
│   ├── scoring/
│   │   └── scorer.js           ← Health score algorithm (0–100)
│   └── ui/
│       └── display.js          ← All terminal output (colors, tables, boxes)
└── README.md

Roadmap

• [x] Phase 1 — Core CLI: search, compare, verdict, scan
• [ ] Phase 2 — --stack nextjs / --stack express context-aware scoring
• [ ] Phase 2 — --json output for scripting and CI pipelines
• [ ] Phase 3 — --share flag: generate a shareable LinkedIn card
• [ ] Phase 3 — pkg-detective trends <category> — growth charts in terminal
• [ ] Phase 3 — GitHub Action: auto-audit deps on every PR
• [ ] Phase 4 — VS Code extension: hover any dep → inline verdict

Contributing

Contributions are welcome!

• Add a new category or packages — edit src/data/categories.js
• Improve scoring logic — edit src/scoring/scorer.js
• Bug reports / ideas — open an issue

git clone https://github.com/majid2851/pkg-detective.git
cd pkg-detective
npm install
node bin/pkg-detective.js auth

License

MIT © Majid

Built with Node.js · Data from npm registry, GitHub API & Bundlephobia