Why you should publish your own npm package and tips for getting it right

Anders Ramsay
Jun 21, 2019 · 6 min read
Image for post
Image for post
The npm package auto-test-file which I recently published

If you’ve been coding apps that use npm packages but have not yet created a package of your own, you should seriously consider making the leap.

Why would you want to publish an npm package?

Getting a first-hand understanding of how packages you install and use in your apps are created can help demystify the potentially intimidating node_modules directory and the inner workings of npm. You’ll likely also find debugging package-related issues to be easier since they now are less of a mysterious black box. And last but not least, I also think the process of writing code that may potentially be re-used by hundreds or even thousands of other developers will drive you to elevate your code quality overall.

Assuming you are creating a public package, by creating an open source project of your own, you’ll be far better prepared to contribute to other such projects. Additionally, you can collaborate with others on the npm package itself, something I would highly recommend.

Publishing an npm package is not something I’d recommend for someone just starting out learning to code, since there is a good chance you’ll get overwhelmed. Focus on the basics for now and make this a future goal.

Also, this is not a tutorial on how to create an npm package, but rather tips for how to help make your package more valuable both to you and others. Check out this tutorial to learn more about the mechanics of creating an npm package.

Figuring out what to publish

Ok, so you’re convinced this is a great idea, but you have no idea what you would create 😞 Here are some tips for getting started.

One can think of a npm package as a product and the developers who install them as customers. If so, the first best customer to start with is you. Think about what are things that bug you, or features you wish you had, while you are coding.

In my case, one thing that was bugging me was finding myself constantly creating test files with the same name as a file I just created but just appending it with “.test” 🤔 Hmm, maybe this can be automated…

And voila, I had my idea for the auto-test-file package.

Image for post
Image for post
A demo of of the auto-test-file package

A great npm package should Do One Thing Well. The more focused your package is on one piece of functionality, rather than some mish-mash of features, the more likely it will be to be useful and reusable.

Now that you’ve got an idea, start with the end in mind

Even if you’ve narrowed down your idea to a specific feature, such as “automatically add a test file when a new code file is added” there are any number of ways that this could be implemented. A great way to figure out what might be the most user-friendly implementation is to start by writing the installation instructions in your README file.

Image for post
Image for post
Install instructions for the auto-test-file package

It might seem counter-intuitive to write a description of your package before you’ve written any code, but the reality is that this will help you articulate what you’re trying to achieve and ensure you write the right code.

The README file, in this context, is basically a description of your imagined future product.

As such, it becomes your high-level coding requirements. You can even use what you write as a starting point for your coding backlog.

Create a separate linked repo for “acceptance testing” of your package

An npm package is something that, by definition, is imported and run in a project other than the one in which it is being developed. Therefore, to test your package, you should create a separate local project and link it to your development project, so that you can simulate a developer installing and using your package. Here’s a great tutorial on linking projects.

By doing this you are effectively doing acceptance testing, ie playing the role of a consumer of your package and interacting with it from that perspective.

Be sure to update your package.json file to include info needed for publishing

Because you are publishing your package, you will want to make sure that it contains all the necessary info that will be needed by npmjs, as well as some optional info that will make your package page more complete. As an example, this the package.json file used for the auto-test-file package.

These are some additional fields that you might not normally include that you should consider adding:

  • Repository: link to github or whatever you use for source control.
  • Keywords: think about what keywords you might use to search for this package and add those.
  • Author: be sure to include an email address for which you have a gravatar icon, eg "Bob Smith <bob@smith.com>" or else npm will display a default gravatar icon.
  • Homepage: just linking to your repo is fine.

Learn more about package.json fields.

Be sure to have good (unit) test coverage

Maybe you normally don’t write unit tests, or maybe it’s something you still are learning. Well, publishing an npm package is a great opportunity to make it a core part of your practice. In other words, for most every function you write, there should be a corresponding set of unit tests.

Image for post
Image for post
A sample unit test

In my opinion, having decent unit test coverage for an npm package is basically a must. Keep in mind that once you publish your package, developers will start downloading and using it and you want to make really sure that things work as expected. In my case, I had nearly 30 downloads in the first few hours of publishing and I had not even promoted the package in any way 😮

Having decent test coverage for an npm package is basically a must.

You therefore want make really sure that your code works as expected and one great way is to have good unit test coverage. For example, here is the These are some sample tests in my package.

Learn more about unit testing. And, hey, to ensure you’re writing tests, why not give my package a whirl? 😉

Let npm handle package versioning

Another important detail is package versioning. The first version of your package should be 1.0.0. With the exception of that first version, you should let npm “bump” the version number, by using the npm-version command. When run, this will also update the version number in your package.json file. You’ll also want to be sure to learn about semantic versioning to know which command to use.

Finally, come up with a decent package name

The strategy I chose for my package name was to simply summarize what the package does. That has the advantage of keeping you focused, but the disadvantage of your name becoming misleading as your package evolves and possibly outgrows some of the original goals. Also, npm package names are a bit like domain names, in that two packages cannot have the same name, so you’ll want to make sure your idea for a name is not already in use.

I hope these tips are useful. They are basically a collection of the insights or snippets of knowledge I wish I had when I set out to create my first npm package.

Coder Chronicles

Thoughts on Designing and Building Digital Products

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store