Why you should publish your own npm package and tips for getting it right
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?
Gain a deeper understanding of the npm eco-system
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.
A great stepping-stone to contributing to open source
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.
If you’re fairly new to coding, this may not be for you
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.
Scratch your own itch
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
Do One Thing Well
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.
Write your README file first
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 <firstname.lastname@example.org>"or else npm will display a default gravatar icon.
- Homepage: just linking to your repo is fine.
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.
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.
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.