In this article, we are going to explore how to publish our open source (OS) code into the npm registry as a module.
npm is currently the largest software repository in the world with over 600 thousand modules published (As of January 2018). It’s used to publish from very small modules (1 line functions) to complete frameworks (like React) and even full P2P clients (like WebTorrent).
Before we continue, this is the list of things we should have beforehand:
Node.js and npm installed (LTS recommended)
An IDE (I’ll be using WebStorm), a few options:
Terminal (I’ll be using iTerm with zsh in MacOS)
1. Creating an npmjs.com account
Our first step is to create an npm account. Now, there are two ways of doing that. The first is through the website and the second is through using npm’s CLI (which you should have installed already) with the command
If you had already created your user or you just did through the website, you must now use
npm login in the terminal to store your credentials.
adduser command should have stored the credentials automatically (
login is just an alias)
To test what we just did, type
npm whoami to ensure that our credentials were stored.
2. Creating our project
Our first step is to create an new GitHub repository, for this tutorial I will be publishing a simple module which wraps async functions with
debug (a logger) logging for
express (a web framework). I’ll call it
express-debug-async-wrap for now. But is it available in the public scope? Just search it or go directly to the package.
If you searched for a simple word, there’s a chance a module that has it in its name or in its keywords and will show up, even then, your package name might be free to take. The safe your is to go directly with this url expression:
https://www.npmjs.com/package/<package name here>
Great, we can proceed with the name
express-debug-async-wrap in mind. Note that we can use any name under our personal scope @username/my-package even if it’s already taken in the public scope.
Naming our modules is an important thing. Recently, npm updated it’s naming rules to prevent name hijacking. You can read more about it in this blog post. We can use A-Z, a-z, 0-9 and punctuations like dots, dashes, and underscores.
Creating the GitHub repository
With our name in mind, we continue to create the GitHub repository. On GitHub go to the top right corner and click the “+“ with an arrow by its side:
We add our project’s name and description. Select “Initialize this project with a README”. And finally, we add Node’s .gitignore and MIT License.
You are free to select the license that best suits you. Learn more here
3. Adding our code
Cloning the GitHub Repository
Initializing the npm package
Once we have the repository, we should “get into” it and initialize the directory with a package.json, to do so, we use
npm init and fill the blanks:
Version should start in 1.0.0 unless we are doing alpha/beta release
Default entry point index.js works for our this first case, but keep in mind if the entry point is different, maybe in
Test command is completely up to you, I use and recommend
standardcode style for linting,
avafor tests for
nycfor code coverage. (These must be installed with as dev dependencies)
Leave git as default, it should be the GitHub repo we just created.
Add as much relevant tags as needed
Match the license chosen in the repo
We now continue with the important part, the code, in a new file called
We must use
exports or the real deal:
module.exports. We can export anything: a function, an object, an array, a class, a string, etc.
Note: To learn the difference between
module.exports we can read more here.
Committing our files to git
We can see the recently created
index.js. In my case, because I’m using WebStorm, I also see a
.idea folder, which is appended to the
.gitignore file to be ignored. Once we’ve ignored the unnecessary files, we add everything and commit:
4. Publishing our module
Although our npm modules don’t have to live in a public repository, I personally think they should, and they should match whatever is stored in the npm registry. So we tag this first version (new releases should be done with
npm version which automatically tags them), push to GitHub, push tags and finally publish to npm:
That’s it! Our module lives in the npm registry.
5. Completing our README
It’s empty and sad, no explanation on how to use it, nothing. We should definitely add a few things: basic badges, how to install, how to use, related packages and a footer stating our copyright and the license. For our module it looks like this:
6. Final touches and homework