5 tips for publishing your first npm package
Table of contents:
If you write code for long enough, you’re bound to reach the point where you have some logic that you’d like to share between your projects, or that you think would be helpful to other developers. NPM can be a great way to make your code easily accessible for both yourself and others.
Who is this post for?
In this post, I’m going to assume that you’ve already made the package and that you’re now ready to publish it. If you’re just getting started with making your package, this post in the npm docs will probably be more helpful for you.
Getting started
The beauty of npm is that anyone can publish a package with just a few commands.
First, you’ll need to make an npm account. You can do this at the npm signup page.
Once your account is created, log in using the command npm login, which will prompt you for your credentials.
Publishing your package
1. Always do a dry run
Before you publish your package to npm, it’s crucial that you double check exactly which files you’ll be publishing. If you run npm publish --dry-run, you’ll be provided with a list of what will be deployed, without deploying anything.
2. Whitelist your package content
The difference between using .npmignore and the files attribute is a classic case of whitelisting versus blacklisting. For the unitiated, .npmignore works in a similar fashion to a .gitignore file. Any file listed in .npmignore will be ignored when publishing your package.
This may seem like a reasonable approach at first. After all, it still gives you control over what gets published. But consider the cost of forgetting to list a file. In the best case, this means that your package is unnecessarily bloated. In the worst case, you could accidentally publish secrets. Remembering to do a dry run can reduce this risk, but we’re all human and mistakes are bound to happen.
To prevent this from happening, you should use the files attribute in your package.json. This field accepts an array of filenames to be included in the published package.
In my package meme-type-npm, I use the following entry for this field.
"files": [
"lib/**/*"
]You may notice that this leaves out common top-level files, such as a README.md or package.json. This is because there are certain default files that npm will always include. You can see more details about this here.
3. Set the value of the main field
In package.json there is a field called main that defines the entrypoint for your package. Essentially, you want this to point to where your modules are being exported.
For example, my package meme-type-npm exports its resources from the location lib/index.js. If I failed to set the value of main, then it would be more complicated for users to import the package.
4. Don’t forget the documentation
If you write a node module in the woods but no one knows how to use it, did you really write a node module?
Writing documentation is one of the most important steps in publishing your code. Unless you clearly tell people what your code does and how to use it, they won’t use it.
Here’s a few things that you should always include in your docs: * A brief summary of the product * Installation instructions * Code examples for common use cases * Links to relevant blog posts, demo videos or live applications, if applicable
5. Make it discoverable
If you’ve gone through the effort of making a package and documenting how to use it, the final step is telling people that it exists.
The easiest way to do this is by adding keywords to your package.json. This gives your project some much-needed SEO and requires little effort, so completing this step is an absolute must.
You can also write blog posts about your project and share them on sites like dev.to or your own personal blog, if you have one.
Finally, share links to these posts on social media. You can participate in a Tuesday evening dev discuss on Twitter, or post to Reddit on r/javascript or r/webdev for their Showoff Saturdays.
If you liked this post, click here to subscribe to my mailing list!