All articles
165 articles · updated weekly See our Tools
All articles
Tips

How to evaluate an npm dependency before installing it

A checklist before npm install: maintenance, adoption, Scorecard, provenance, transitive dependencies, and license to tell if a package is safe.

How to evaluate an npm dependency before installing it
COVER · Tips

You need a slug function, find a package at the top of the search results, run npm install, and thirty seconds later the dependency is on its way to production. What you didn't see: that package pulls in twelve others, one of them runs a postinstall script, and the sole maintainer publishes from an account that can be hijacked with a well-crafted phishing email. That's exactly how malicious versions of chalk and debug got published on September 8, 2025, after a fake "npm support" email (Semgrep).

This post is the check I run before npm install: ten minutes to decide whether a package deserves a place in the project. It's one of three on the same subject. For what's already installed and stopped getting maintenance, see abandoned dependencies. For trimming what's left over, how to reduce dependencies. Here the focus is the front gate.

Before evaluating: do you actually need it?

Every dependency is attack surface and update work. If the package only wraps something the language already does (String.prototype.padStart has existed since ES2017; left-pad itself now shows up on npm as deprecated with the message "use String.prototype.padStart()"), write the five lines. I go deeper into that criterion in how to reduce dependencies. If the answer is "yes, I need it," keep going.

Signal 1: maintenance, in two commands

You don't need to open GitHub for the first pass. The registry answers almost everything:

# publish date of every version (the last lines show the current pace)
npm view express time --json | tail -4

# license, current version, maintainers, and repository
npm view express version license maintainers repository.url

I ran this in a node:22 container (npm 10.9) on 2026-11-09: express had 5.3.0 published on 2026-10-09, a 4.22.3 maintenance release on 2026-09-14, an MIT license, and five listed maintainers. A regular release cadence and more than one person with publish rights is what you want to see.

A package with no release in two years isn't automatically bad (small, stable code exists), but combined with unanswered issues it becomes a red flag. The signal that weighs most is how many people actually maintain it; how to read that is covered in abandoned dependencies.

Signal 2: adoption (at a discount)

Weekly downloads and number of dependents tell you how many people already bet on that code. More eyes mean bugs and vulnerabilities get found faster. But popularity doesn't protect against compromise: chalk and debug are among the most downloaded packages on npm and were precisely the target in September 2025, because a poisoned popular package reaches more machines. Use adoption as a sign the code gets exercised, not as proof that it's safe.

Signal 3: what the package brings along

Here's the most common mistake, one I used to make myself: using npm ls <package> to see "what the lib drags in." npm ls shows the path to the package in your tree, that is, who depends on it, not its dependencies. To evaluate before installing:

# direct dependencies the package declares
npm view express dependencies

# how many packages would actually come in, without installing anything
npm install express --dry-run

In the same container, express 5.3.0 declared 28 direct dependencies, and --dry-run in an empty project reported added 65 packages. That's the number that matters: 65 packages, from dozens of maintainers, running with the same privileges as your code.

Once installed, the right command to answer "why is this package here?" is npm explain:

npm explain debug
# debug@2.6.9
#   debug@"2.6.9" from body-parser@1.20.9
#     body-parser@"~1.20.5" from express@4.22.3
#   ...

If you want to read a candidate's package.json calmly (the dependencies, scripts, license, and engines fields), npm view <package> --json returns it all at once; pasting the output into a JSON formatter makes the structure legible and helps you find the scripts block fast.

Signal 4: security and the supply chain

npm audit is the floor: it checks the tree against vulnerabilities that are already known and published. It won't catch a freshly compromised package or a backdoor nobody has reported. Three checks complement it:

OpenSSF Scorecard. Scorecard gives a repository a 0–10 score from automated checks: maintenance, code review, branch protection, dangerous workflows, security policy, signed releases. You can query it via API:

curl -s https://api.securityscorecards.dev/projects/github.com/expressjs/express
# "score": 8.9  (queried 2026-11-09; analysis dated 2026-11-02)

A high score isn't a guarantee, it's triage: a repository at 3/10 with no code review deserves a longer look. Google's deps.dev shows the same information alongside the dependency graph and known advisories for each version.

Provenance. Packages published from CI with provenance carry an attestation that ties the tarball to the commit and workflow that built it. After installing, check:

npm audit signatures
# 68 packages have verified registry signatures
# 4 packages have verified attestations

That output is real, from a project with express@4. The first line (registry signatures) should always be 100%. The second shows how many packages have provenance; it's still a minority, and a critical package that starts publishing without provenance after having had it is a reason to investigate.

Install scripts. npm view <package> scripts shows whether there's a preinstall, install, or postinstall. esbuild, for example, has "postinstall": "node install.js", which is legitimate (it downloads the platform binary), but that's exactly the hook worms use. The first Shai-Hulud wave, in September 2025, started with a malicious version of @ctrl/tinycolor and used install scripts to steal tokens and republish itself into the victims' packages; CISA issued an alert on 2025-09-23 citing more than 500 affected packages. If you can't justify a package's install script, install with --ignore-scripts and see what breaks.

And the case everyone cites, xz: the "Jia Tan" persona sent a first harmless patch in October 2021, and the backdoor was only discovered in March 2024 (CVE-2024-3094), per Russ Cox's timeline. That's more than two years earning trust until becoming co-maintainer. No npm audit would catch that; what reduces the risk is knowing who publishes and preferring projects with code review.

Signal 5: license

A missing license means "all rights reserved": you have no permission to use the code. MIT, Apache-2.0, and BSD are permissive and fine for almost any project. With GPL the nuance is what triggers the obligation: it applies when you distribute the software (a binary, an installable app, a package). Running the code only on your own server, as SaaS, isn't distribution under the GPL; that's why the AGPL exists, extending the obligation to anyone offering the software over a network. The practical differences are in MIT, Apache, and GPL licenses. The license field comes out of the same npm view from Signal 1.

A 10-minute checklist before npm install

  1. Do I actually need it, or does the language already solve this?
  2. npm view <package> time --json: a release in the last 12 months, or is the code small and stable?
  3. npm view <package> maintainers: does more than one person publish?
  4. Does the linked repository exist and is it the same project? (A name close to a famous package is a typosquatting sign.)
  5. npm view <package> dependencies and npm install <package> --dry-run: how many packages actually come in?
  6. npm view <package> scripts: is there a preinstall/install/postinstall? Why?
  7. Scorecard or deps.dev: a reasonable score, no open advisory on the version you'll use?
  8. License compatible with your use (distribution or SaaS)?
  9. After installing: npm audit and npm audit signatures clean.
  10. Lockfile committed, so the tree you evaluated is the same one that ships to production.

Frequently asked questions

How do I know if an npm package is safe?

There's no guarantee, only risk reduction. Check who publishes and how often (npm view), what it brings along (--dry-run), whether it runs install scripts, its OpenSSF Scorecard score, and whether npm audit and npm audit signatures pass. A popular package maintained by several people, with provenance and no install scripts, is the safest bet you can make.

What is the OpenSSF Scorecard?

It's a tool from the Open Source Security Foundation that evaluates repositories with automated checks (maintenance, code review, branch protection, dangerous CI workflows, security policy) and gives a 0–10 score. It's for triage: compare candidates quickly and see where to look harder. It doesn't detect malicious code.

Does npm audit guarantee my dependency is safe?

No. It only compares the tree against vulnerabilities that are already known and published. A package compromised an hour ago, or with a backdoor nobody has reported, passes clean. Treat it as a floor and combine it with the other checks.

How do I see what a package installs before installing it?

npm view <package> dependencies lists the direct dependencies, and npm install <package> --dry-run shows how many packages would come in overall, without writing anything. Once installed, npm explain <package> answers why a package is in the tree; npm ls <package> shows who depends on it.

Evaluate at the gate, not at the incident

Ten minutes before the install cost less than a night spent rotating tokens. Ask whether you need it, look at who maintains it and how often, count what comes along, be suspicious of install scripts, use Scorecard and provenance as triage, and read the license with the right nuance. Once the package is in, the conversation changes: tracking whether it stays alive is the subject of abandoned dependencies, and why so many critical packages depend on one or two people in their spare time becomes clearer after you contribute to open source yourself.

RD
Author
Rafael Duarte
Backend developer with a background in fintech and B2B SaaS — worked on teams that scaled APIs from zero to millions of requests. Carries enough production scars to hold strong opinions on tools, patterns and architecture decisions. Not an academic: he read the UUID RFC when he had to choose between v4 and v7 for a write-heavy table.
View profile