How to Analyze Your NPM Dependencies for Better, More Maintainable Code

A complete, beginner-friendly guide to understanding the state of your npm dependencies

Ryan J. Yost
Feb 5 · 12 min read
Image from Wikipedia

In this guide, I’m going to walk you through the things I consider when assessing the state of my npm dependencies — with the goal of improving my software and making it more maintainable.


Why Read This?

Back in the day, you used to be able to rely on vanilla JS or jQuery to handle the interactivity of your applications. But now, powerful frameworks like React, Vue, etc. — and the myriad amazing libraries that work with them — make it super beneficial to leverage open-source solutions to our technical problems.

npm makes it easy to incorporate these third-party solutions into our code — so easy we can take our deps for granted and forget they aren’t just magical black boxes we can stop worrying about once implemented.

Lots can evolve — and devolve — concerning your dependencies that can come back to bite you later if you aren’t paying attention.


Why I Wrote This

To scratch my own itch and save time when assessing the current health of my dependencies, I built a simple tool called DepChecker that automatically gathers info about and analyzes the dependencies in a package.json file. It basically does what this piece walks through.


OK, Let’s Analyze Some Dependencies

for (let dependency of dependencies) { 
const infoAboutDependency = []
for (let factor of factors) {
const info = gatherInfo(dependency, factor)
infoAboutDependency.push(info)
}
makeAssessment(infoAboutDependency)
}

There are a variety of useful factors that shed light on the state of your dependencies. The list we’ll walk through isn’t exhaustive, but it’s the one I use and is pretty thorough.

The factors to consider are:

  1. Is the dependency still being used in your project?
  2. How many versions behind the current release are you?
  3. When was the dependency last updated?
  4. How many weekly downloads does the package have?
  5. How many GitHub stars does it have?
  6. How many open issues and pull requests are there?
  7. What’s the project’s license?

For each factor, I’ll break down the following things:

  • Where to find info about it
  • How to assess and make sense of the info you find
  • Why you should care

Factor 1: What Does the Dependency Do?

Where to find info about it

  • The package’s page on npmjs.org (e.g., React)
  • The GitHub repository (e.g., Express)
  • And, if available, the project’s site/documentation (e.g., Vue.js)

This should be plenty to understand its purpose.

Manually searching for each dependency can be annoying, so you can use a tool like DepChecker, which quickly gathers the description and all of the important links for you.

How to assess the info

Why you should care


Factor 2: Is the Dependency Still Being Used in Your Project?

Where to find info about it

  1. Perform a global text search for the dependency name, and see if it’s being used anywhere.
  2. Sometimes, weird dependencies like Babel plugins won’t show up exactly in your project, but they’re still being used. So one way to check whether it’s needed is to remove it and run your app along with any tests.

How to assess the info

  1. Be careful! depcheck is awesome, but it’s not 100% accurate. You should verify some other things before deleting it from your package.json.
  2. If it’s imported, is the module actually used in the code? If not, then maybe it’s no longer needed.
  3. If the tests pass and all looks good, it can be reasonably assumed the dependency isn’t needed anymore.

Why you should care

  • Future contributors to your codebase might think it’s OK , or even encouraged, to use the dependency if it’s already installed, which might not be ideal for your team and the code practices you’re trying to implement
  • An unused dependency just sitting in your project can introduce a compiling/transpiling bug or security vulnerability down the road

Factor 3: How Many Versions Behind the Latest Release Are You?

Where to find info about it

To find your project’s version, go to your package.json and find the package name key in the object of dependencies or devDependencies. The project version will be the value for that key.

With tools like npm-check and DepChecker, you can get a nice, color-coded printout of the latest version, your version, and how far behind your version is.

How to assess the info

  • PATCH (x.x.0) — This denotes “backwards compatible bug fixes.” So if your version is just patches behind (like the Lodash example in the screenshots above), you can pretty safely just bump the version.
  • MINOR (x.0.x) — This denotes new functionality that’s been added “in a backwards compatible manner.” Again, it’s probably safe to upgrade so long as the tests all pass.
  • MAJOR (0.x.x) — This denotes “incompatible API changes” and requires diving into the changelogs, release notes, and other documentation in order to figure out the implications of doing aMAJOR version upgrade. You'll probably need to do some manual refactoring with a MAJOR version upgrade.

As a general note, upgrading your project’s dependency versions is safest with plenty of test coverage and a CI/CD pipeline. Awesome free tools like Dependabot can help automate this for you.

Why you should care


Factor 4: When Was the Dependency Last Updated?

Where to find info about it

For more details about exact dates of version releases, you’ll have to check out any releases on GitHub or use the npm repository API.

How to assess the info

If a package hasn’t been updated for a year or more, on the other hand, that could signify the package is no longer maintained and is neglected.

How to interpret the exact time since last publish can vary from package to package, depending on its nature. For example, a library of basic statistics probably doesn’t need to be updated that often. Though in the modern age of JavaScript, not updating for a while has the potential for compiling issues or becoming vulnerable to incompatible versions of other dependencies.

I have some general, subjective rules of thumb in my head for how long it’s been since the last publish:

  • Less than two months — Good
  • Less than six months — Fine
  • Less than a year ago — Warning
  • More than a year ago — Danger

Why you should care

If a dependency of yours is updated very often, it generally means you can confidently continue to use it and benefit from improvements in the future. On the other hand, a neglected package threatens your codebase and likely needs to be replaced by a comparable dependency before it causes bugs and issues for your team.


Factor 5: How Many Weekly Downloads Does the Package Have?

Where to find info about it

How to assess the info

Here are my subjective rules of thumb for weekly download counts:

  • More than 100,000 — Good
  • Less than 100,000 — Fine
  • Less than 10,000 — Caution
  • Less than 1,000 — Extra Caution! Do some digging as to why the number is low. Is it brand new? Solves a super niche problem?

Trends in downloads are also helpful

  • If going down, it could mean the package has a superior alternative, that it’s neglected, that it isn’t needed anymore, etc.

In addition to the tiny trend line on the npmjs.org site, there’s a cool website called npm trends where you can dive deep into npm download trends.

Why you should care

  • When deciding on what npm package alternative (e.g., Angular vs. React vs. Vue) to use in your project, the download trends can be telling of what the community thinks is superior/inferior
  • Downward trends can warn you about a dying dependency and allow you to preemptively remove or replace it before it negatively impacts your project

Factor 6: How Many GitHub Stars Does It Have?

Where to find info about it

How to assess the info

But be careful! A high star count isn’t enough to sign off on using/keeping a dependency, because stars accumulate over time. It’s possible the project has 20k stars, but the last star was a year ago or it’s just deprecated.

Like the weekly downloads, trends are just as important as the current total of stars. There’s a couple cool websites, like Star history and this one, that show GitHub-star trend lines.

Here are my subjective rules of thumb for GitHub stars:

  • More than 1,000 — Good
  • Less than 1,000 — Fine
  • Less than 300 — Caution
  • Less than 50 — Extra Caution! You should do some more due diligence on this.

Thanks to Keagan Chisnall for pointing out in a comment below that a low GitHub star (and I guess low weekly download count, too) doesn’t necessarily make an npm package bad/dangerous, it just means you have to do some more digging/research on your own to really justify why you’re going to make it a dependency in your project.

Why you should care


Factor 7: How Many Open Issues and Pull Requests Are There?

Where to find info about it

How to assess the info

  • How active the open-source community surrounding the project is
  • To what extent the project has bugs or lacks desired functionality
  • How active the maintainers are

If the number of open pull requests is high that could show the community is desperate for improvements, but the maintainers are asleep at the wheel or not accepting outside help — not a good sign.

The absolute number of open issues and PRs can be misleading — bigger projects with more users should naturally have more issues on GitHub, and vice versa.

So you’ll want to normalize the number of open issues in your head to account for this. While far from scientific, you could think of a rough ratio of open issues and PRs to weekly downloads. The smaller the ratio, the better.

Why you should care

  • Tons of bugs in the open pull requests isn’t a great sign for a piece of software you want to include in your own
  • Good and bad signs can be gleaned from the current state of a dependency’s open issues and pull requests — so it’s valuable to pay attention

Factor 8: What’s the Project License?

Where to find info about it

For details of particular licenses, Google and this table breakdown are helpful.

How to assess the info

Most of them you don’t have to worry about, but if an npm dependency of yours doesn’t use the classic, free-rein MIT license, then it’s prudent you figure out the implications of the license for your software, especially if you’re using it in commercial software.

Here’s a great article with more on that.

Why you should care


Conclusion

List of Tools to Help You Manage Dependencies

Other links

Better Programming

Advice for programmers.

Thanks to Zack Shapiro

Ryan J. Yost

Written by

Working on depchecker.com

Better Programming

Advice for programmers.

More From Medium

More from Better Programming

More from Better Programming

More from Better Programming

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade