Add standardized support information to your Node.js modules

The Nodeshift team recently improved the consistency of the projects we use to maintain our Node.js modules. We made sure that the same linter and tests—ESLint and Tape, for those interested—were used on all projects. We also added support information for the modules we publish to the npm registry. We looked to the Node.js Package Maintenance Working Group for the standardized support information to add.

In this article, I detail the changes we made based on the Package Maintenance Working Group's recommended best practices. After reading the article, you'll be familiar with the recommended support information and the tools available for adding it to your Node.js modules. First, I will introduce the Node.js Package Maintenance Working Group and its purpose.

The Node.js Package Maintenance Working Group

The Node.js Package Maintenance Working Group was created to help package maintainers and consumers navigate the ever-growing Node.js module ecosystem. The working group has a few specific goals. One of those goals is to help package maintainers communicate with and set expectations for their users. The working group recommends providing information such as the project's level of backing, the target level of support, and what versions of Node.js will eventually be supported for every Node.js module. Users can then select modules that are a good fit for their functional and business needs.

Note: For a more in-depth look at the Node.js Package Maintenance Working Group's recommendations, check out Node.js package maintenance: Bridging the gap between maintainers and consumers on the OpenJSF project page.

The working group created an initial set of best practices that anyone who maintains and consumes packages can use when adding a support policy to their modules. The easiest way to add this standardized information to your Node.js modules is to create a separate file called package-support.json, which lives at the root of the package. You can then add the support parameter to the package.json with a value of true.

Updating the Nodeshift modules

More advanced options are available, but we decided to only add the support: true parameter to our package.json and store support information in a separate file, package-support.json.

Here are the contents of the package-support.json for Opossum, one of our modules:

{
  "versions": [
    {
      "version": "*",
      "target": {
        "node": "lts"
      },
      "response": {
        "type": "regular-7"
      },
      "backing": {
        "company": "true"
      }
    }
  ]
}

Let's unpack the fields here:

• First, we have the top-level versions property, which in our case is an array. This property contains information for a package version range. We have only one entry in our array.
• The next field is version, which specifies the module version or versions that are supported. This could be a semantic versioning (SemVer) range, but in our case, we use *, signifying all versions.
• Next, we have the target property, which tells us the platform version we'll support. In our case, we are running on Node.js and plan to support currently active long-term support (LTS) versions. This means that as Node.js versions become LTS, we will support them. Similarly, as Node.js versions enter end-of-life (EOL), we will no longer support them.
• We next specify that our response is regular-7, which means that dedicated folks maintain this package and users can expect a response within seven days or fewer.
• Lastly, our backing property is set to company, because it is part of our day job to maintain these packages.

Each of these fields has more advanced options, so please see the "Format and Structure" section of the package maintenance team documents to learn more.

Validating support information (@pkgjs/support)

Now that we have added the support file to our module, we, as maintainers of the module, want to check that the information we added to the package.json and the package-support.json is valid.

For this, we can use a tool from the Node.js Package Maintenance Working Group called @pkgjs/support. To start, we run the validate command from our module's root to make sure it is valid:

npx @pkgjs/support validate

Because we are using GitHub actions, we’ve put this command in our continuous integration (CI) pipeline to test that our support information is valid whenever the integration is run. We also package consumers, and our module has dependencies, so we add another important command called show:

npx @pkgjs/support show

This command allows us to view and understand the support information that other maintainers might provide. Right now, the command's implementation is very basic, but we expect it to evolve and grow over time, much like the tools that use the license information provided in package.json.

Conclusion

As you've seen, adding support information for a Node.js module can be very simple and beneficial to the module's users and the Node.js module ecosystem as a whole. We hope you join us in adding the recommended support information to your modules. We believe it’s a good way for a maintainer to help set expectations. As Node.js use becomes more widespread, support information will be important to ensure a good match between users' expectations and the modules they use.

While this article only covers the basic commands, more advanced options are available. To learn more about the @pkgjs/support tool or the Node.js Package Maintenance Working Group, see the project's GitHub repository.