With almost half a million packages at the time this post was written, the possibilities are endless. But, how do you choose which packages to include in your project and which functionality to build for yourself? Luckily NPM provides us with some indicators for the quality of the packages it offers, but the decision is still a difficult one to make and depends greatly on factors like the size of your project and the timeframe you’re working under.

Regardless of these factors, here are some things you should keep in mind when choosing which NPM packages to add to you’re project:

  • Tests
  • Code Coverage
  • Documentation
  • Proper Versioning
  • Code Quality
  • Repository Activity
  • Authors
  • Popularity

Tests

Keep an eye out for this badge: Build Status generated by travis-ci or something similar in the module README to let you know if a module is implementing proper tests and making sure that those tests actually pass.

If badges are absent, look for a test folder inside of the module directory. If it’s there, cd into the directory and run npm test (usually) to run the test suite.

Code Coverage

Similar to the travis-ci badge coveralls offers it’s own badge to reassure users that the code is fully tested: Coverage Status. While testing is invaluable, it doesn’t count for much if it isn’t also thorough. tools like Blanket.js and coveralls allow you to feel secure in how completely the module you’re using was tested.

Documentation

The quality of the documentation in the README is a great indicator of the quality of the module. A poorly or undocumented module is all but useless for most people and should immediately raise red-flags.

The README file should contain, at the very least, the name of the module, a description, installation instructions, examples on how to use it, and a license.

Most modules are simple enough that their documentation can all fit in the Readme. Bigger modules will have a separate documentation folder at the root of their project, a wiki in the GitHub repository, or a dedicated website.

Proper Versioning

All modules should follow the Semantic Versioning specification (semver). it can be summarized as:

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,
    • MINOR version when you add functionality in a backwards-compatible manner, and
    • PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

NPM provides a handy tool to ensure that updating your packages won’t break things: next-update. This will test to see if a package can be updated without breaking any of the tests.

Code Quality

CodeClimate Although the quality of the code isn’t an easily quantifiable property, some tools like JSHint or Code Climate can make it clear what the quality of code is. Code Climate also provides badges to be embedded in READMEs like this: Code Climate.

Regardless of whether or not you use a code evaluation tool, you should always look through the code of any package you’re using to make sure that it isn’t introducing any security issues.

Repository Activity

Support is essential for any package you’re using in a large project. Having to maintain packages in addition to your projects code base quickly leads to an overwhelming amount of work. Luckily, since most packages are hosted on GitHub, you can easily check the activity of the package repository. Keep an eye out for things like the date of the last commit, the number of open issues, the number of open pull requests, etc.

Note, that an inactive package repository doesn’t mean that you shouldn’t use that package. If a package has no open issues or pull requests, then the author may just consider the package complete.

Authors

Knowing the author of the package will also give a good indication of whether or not a package will be supported. Look at what other repositories that author has and what the support has been like for those repositories to get a good sense on how well they will maintain the package you’re considering.

Popularity

While the popularity is not an indicator of the good health of a package, it can indicate that a lot of people already trust it and its authors. Chances are if there is a problem with the support and the package is still widely used, it will be forked and/or maintained by some other contributors.

For more information on authoring your own packages, check out this blog post.