Woman on ComputerNode Package Manager (npm) is one of the most powerful tools available to JavaScript developers. It allows anyone to share open-source projects with the world. It is relatively easy to publish a library on npm, but there are a few things developers need to consider before sharing code with the open-source community. In this blog I will discuss some tips that developers should follow in order to publish a high quality JavaScript library.

Quality Code

This seems like a no brainer, but it is especially important when the code is to be shared with the open-source community. A lot can be said when referring to code quality, but there are two items that are worth discussing:

Linting

Implementing a JavaScript linter is one of the easiest ways to improve code quality. A linter's main purpose is to scan your code looking for mistakes. It is perfect for enforcing good coding practices, identifying errors before they happen and ensuring a consistent coding style. An added benefit of using a JavaScript linter is that it can help make your code more readable. Plenty of developers prefer to read the code as opposed to reading documentation; linters can assist in achieving that goal.

Error Handling

Nothing is more frustrating than seeing a cryptic error originating from third-party code and not having any idea what might be the cause. It can also be hard to tell if there is something wrong with the code itself or if the developer made a mistake when trying to use a feature of the library. Catching errors and providing informative error messages is extremely useful for a developer. We are not just talking about catching JavaScript error types like Reference Error and Type Error. Catching user errors, and alerting the developer of the mistakes and how to fix them is very helpful.

Limit Dependencies

If possible, limit your library's number of dependencies. Adding too many dependencies can bloat your library, making it less desirable for others to use. Also, managing many dependencies can be very difficult and can create a lot of extra work. As a new version of a dependency becomes available or an old version is no longer supported, code changes are often required to stay up to date, or to keep your library from breaking. One extreme example of a dependency causing problems is when one developer broke thousands of projects by removing left-pad from npm. That story is a perfect example of a dependency that can easily be removed by just taking the time to rewrite the function yourself.

Universal Module Definition

Assuming the library is using JavaScript modules, it is highly recommended that the modules work everywhere (i.e. client and server) with a variety of module loaders (i.e. RequireJS, Browserify). The UMD pattern provides this capability by exporting the library's modules to AMD, CommonJS, and as property root. There are a variety of ways to implement UMD, but I recommend using Webpack. By setting output.library to the name of the library and output.libraryTarget to UMD in the webpack.config.js file, your library now supports multiple module definitions. Using UMD gives the end user the freedom to choose the tooling they want to use without having to adhere to a certain module format.

Unit Testing

Creating a test suite is important for many obvious reasons, but when creating a public library, tests can set a high level of trust with the consumer. Creating a solid set of tests with around 80% or higher code coverage will potentially ease concerns of a new user looking at consuming the library. I recommend implementing a trusted JavaScript testing framework like Jasmine or Mocha. Istanbul is a great tool that will report code coverage so gaps in unit tests can easily be identified.

CI/CD

Once tools like linters and unit tests are added to the library, it would be nice to not have to run them manually for every commit. Creating a CI/CD pipeline will automate this process, and there are some great tools that you can use. My recommendation is Travis CI. It is extremely easy to set up and integrates well with GitHub. In fact, you can display a badge on the READ.ME that will indicate to the end user whether the current build is passing or failing. There are plenty of different processes that can be added to a CI/CD pipeline, but at a minimum there should be a process to run a code scan and a process to run the unit tests.

Documentation

All of these "tips for publishing to npm" are not just for the developer(s) that maintain the library. It is all about demonstrating that the library is of high quality and creating a high level of trust with the end user. Another piece to this is creating detailed documentation. A user should be able to learn everything they need to know about the library through the documentation and only look at the source code if they are interested. I like to break up my documentation into these sections: Overview, Install, Quick Guide, Specs, and Examples.

Overview

A quick description of the library. What does it do? What problem does it solve? Why was it created?

Install

Instructions for how to implement the library.

Quick Guide

Instructions for how the developer can quickly start using the core functionality of the library. No need to present complex implementations.

Specs

Highly detailed descriptions of each component of the library.

Examples

Depending on the library, examples are not always needed, but it is great to provide a variety of implementations/use cases of the library. A demo of the library in action with a link to the source code can be really helpful.

Publish Library

Once the JavaScript library is completed, implementing all or most of the tips above, it is time to publish the library to npm. As stated previously, this is extremely easy. First, go to npm and create an account. Once that is complete execute npm login. Next, configure the package.json file. Below is a generic example:

{
 "name": "libraryname",
 "version": "1.0.0",
 "description": "Description of your library",
 "main": "main.js",
 "keywords": [
 "JavaScript",
 "library"
 ],
 "author": "Your Name",
 "license": "MIT",
 "repository": {
 "type": "git",
 "url": "git@github.com:location/ofGitRepo.git"
 }
Lastly, execute npm publish. That's it! Your library is now on npm!