How to Evaluate npm Package Health Before Installing

TL;DR

Before installing any package, run a 2-minute health check. Most dependency regrets come from skipping this step. Check: weekly downloads trend (not count), last release date, open issues vs closed ratio, bundle size, TypeScript support, and whether there's an actively maintained alternative. PkgPulse automates this with a composite health score — use it to compare before you commit.

Key Takeaways

• Downloads trend beats download count — is it growing or declining?
• Last release date matters for security — >12 months is a yellow flag
• Bundle size should match the problem size — a utility shouldn't be 200KB
• License check prevents legal issues — MIT/Apache-2 for commercial use
• Health score combines all signals — use PkgPulse before adding dependencies

---

The 2-Minute Health Check

Check 1: Download Trend

# Go to npmtrends.com or pkgpulse.com/compare
# Search for your package vs its top competitor

# What to look for:
✅ Growing (week-over-week, month-over-month)
✅ Stable with high absolute numbers
⚠️  Flat for 12+ months → potentially stagnant
⚠️  Declining 20%+ year-over-year → developers moving away
❌ Cliff drop → major breaking issue or community exodus

# Example: date-fns vs moment.js
# moment.js: 14M/week but declining every quarter
# date-fns: 50M/week and growing
# The trend tells you which the community is choosing NOW

Check 2: Last Release

# Check on npmjs.com (package page shows "x days ago")
# Or GitHub releases tab

✅ Released in last 3 months → actively maintained
✅ Released 3-12 months ago → healthy cadence
⚠️  Last release 12-24 months ago → investigate
❌ Last release 2+ years ago → likely abandoned (unless intentionally stable)

# Context matters:
# lodash: low release cadence is fine — it's a stable utility library
# A security library that hasn't released in 2 years? Red flag.

Check 3: Bundle Size

# bundlephobia.com — search any npm package

# What to look for:
✅ Size appropriate for functionality (utility = <5KB, UI library = <50KB)
✅ Tree-shakeable (only import what you use)
⚠️  Large library for simple task (100KB for date formatting = no)
❌ Not tree-shakeable + large = always pays the full cost

# Rule of thumb by category:
# Utility functions:   <5KB gzipped
# Validation library:  5-15KB gzipped
# State manager:       2-30KB gzipped
# UI component library: 10-100KB (but should be tree-shakeable)
# ORM:                 varies (Prisma is large but most is codegen)

Check 4: TypeScript Support

# Check package.json for "types" field
cat node_modules/your-package/package.json | grep '"types"'

# Or check npmjs.com — shows "DT" badge if uses DefinitelyTyped
# Shows "TS" badge if ships types natively (preferred)

✅ Ships native TypeScript types (package.json "types" field)
✅ @types/package actively maintained (check @types/* downloads)
⚠️  @types/ exists but is months behind the package
❌ No types at all → you'll be casting to `any` everywhere

Check 5: Open Issues + PR Health

# GitHub → Issues tab
# Look at: total open issues, issue age, maintainer responses

✅ Issues triaged within 2 weeks
✅ Open:Closed ratio below 1:3 (few open vs many closed)
✅ P0/security issues resolved promptly
⚠️  Issues sitting 60+ days with no response
❌ Known security vulnerabilities with no patch
❌ Maintainer's last response was "I'll look at this" 8 months ago

Check 6: License

# Check SPDX license identifier
cat node_modules/your-package/package.json | grep '"license"'

# Common licenses for commercial use:
✅ MIT → can use, modify, distribute (most permissive)
✅ Apache-2.0 → similar to MIT, explicit patent grant
✅ BSD-2-Clause, BSD-3-Clause → permissive
⚠️  GPL-2.0/GPL-3.0 → copyleft: your code may need to be open source
⚠️  AGPL-3.0 → very strong copyleft (includes network use)
❌ BUSL-1.1 (Business Source License) → not open source for commercial use
❌ Proprietary → read the terms

# When in doubt: run `license-checker` in your project
npx license-checker --summary

---

The Full Checklist

## Pre-Install Checklist for: [package-name]

### Basics
- [ ] What problem does it solve? (define clearly before searching)
- [ ] Is there a simpler native alternative? (e.g., `fetch` vs axios for simple use cases)
- [ ] How many packages does it add? (`npm install --dry-run`)

### Health Signals
- [ ] Weekly downloads: _______  Trend: ⬆️/➡️/⬇️
- [ ] Last release: _______ (< 12 months = ✅)
- [ ] Bundle size: _______ gzipped  Tree-shakeable: Y/N
- [ ] TypeScript: Native / DefinitelyTyped / None
- [ ] Open issues: _______ vs Closed: _______
- [ ] License: _______ (MIT/Apache OK for commercial use)

### Security
- [ ] Known CVEs? `npm audit` after install
- [ ] Dependency tree depth (deep trees = more attack surface)
- [ ] Maintainer reputation (individual or org? active?)

### Alternatives Considered
- [ ] Compared to: _______
- [ ] Reason for choosing: _______

### Decision
- [ ] Install? Y/N
- [ ] Monitor via: PkgPulse / npm audit CI / Dependabot

---

Using PkgPulse Health Scores

PkgPulse health score dimensions:

1. Popularity (20%)
   → Download velocity, trend direction, GitHub stars

2. Maintenance (35%)
   → Release frequency, commit activity, issue response time
   → Most important dimension — predicts long-term viability

3. Community (25%)
   → Contributors, forks, StackOverflow questions, ecosystem articles

4. Security (20%)
   → Known CVEs, dependency vulnerability count, last security patch

Health score ranges:
90-100: Excellent — widely used, actively maintained, minimal risk
70-89:  Good — stable with room to improve
50-69:  Caution — investigate specific low-scoring dimensions
<50:    High risk — consider alternatives

Example use:
pkgpulse.com/compare/prisma-vs-drizzle
→ Shows health scores side-by-side
→ Shows download trends over 12 months
→ Shows bundle sizes, TypeScript support, license

---

Search and compare npm package health at PkgPulse.