How To Publish Your Own NPM Module
Share your re-useable code publicly or privately. Making an NPM Module is useful to understand whether you are coding in a corporate environment or just for fun.
In this blog post I’ll be going over how to make a super simple npm module — explaining the process while also touching on some important concepts of NPM as I go.
By the end of this post we will have made an npm account, an npm module, and also imported the module into another application for use.
You can view the finished module here on NPM:
Command Line Use: I’m assuming if you are reading this, that you already havesome experience with the command line or terminal on your computer.
Prereqs: The only prerequisite for this tutorial is the NPM CLI Tools. If you have node.js installed on your computer, you have NPM and the NPM CLI already installed. So o
One thing to note is that “node modules”, “node packages”, “NPM Modules” and “NPM Packages” are used pretty much interchangeably. Don’t worry if I swap them around a bit, even in this post.
The Steps to make a Module:
- Make an NPM account
- Log Into NPM Via the NPM CLI
- Make an NPM package
- Publish your NPM Module to the registry
- Pull your NPM Module down from the registry for use in a new app
- Configure + Modify
Let’s get started!
1. Make an NPM Account
Just do it. The NPM website is here, at npmjs.com. It’s pretty straightforward, the only snag that I came across is that you’ll need to verify your email address BEFORE you try to publish your npm module. If you don’t, things will get weird.
2. Log Into NPM Via the NPM CLI
Open your terminal and type:
That will lead you through some simple questions and you will end up authenticated with npm, which will be important for when you try to publish your code to NPM later.
3. Make an NPM Module
This is the fun part. First make an empty folder (the name is actually not important and can be different from the final module name). Make a file in that directory called index.js. This is by convention the file that will be imported when people use your module. Open up that file and put the following JS code in there. Feel free to make the function do whatever you want, the only important part is the
module.exports code at the bottom.
The next step is to initialize the folder that you are in as an NPM Module. To do that just go into terminal and type
npm init will guide you through a few steps, just keep pressing enter to continue through these, there’s nothing that you need to select, feel free to go with defaults.
This command creates a JSON file with the contents of your new module. These will be the details that will be communicated to the NPM registry when you publish.
4. Publish your node module to the registry
This one is pretty simple, just go to the terminal in the root of your folder and use the command
This will start the deployment of your package to the NPM registry. If all goes well you should see a dialogue like this:
npm notice 📦 firstname.lastname@example.org
npm notice === Tarball Contents ===
npm notice 455B index.js
npm notice 212B package.json
npm notice === Tarball Details ===
npm notice name: holidaygenerator
npm notice version: 1.0.0
npm notice package size: 478 B
npm notice unpacked size: 667 B
npm notice shasum: 1e9b9360199179cbffcd1f095492b17c1d0b9409
npm notice integrity: sha512-YbKgmIvX4cFNc[…]hWro/6voQ2tOg==
npm notice total files: 2
Which is essentially saying that your code has been packaged and moved online. To be safe, quickly check that your package was published successfully:
Go to npmjs.com/[yourpackagename] and check. It should look like this: https://www.npmjs.com/package/holidaygenerator.
5. Pull your NPM Module down from the registry
It’s great that your code is now on the internet, but it would be nice to actually use that code, right? To use your package you will need to pull it down into another project and then reference it using the require syntax. As setup let’s first take the following steps:
- Make another folder
- In that folder, run
npm initagain (defaults are still fine)
- Create another .js file called
- Copy the following code into that js file
What we’ve built is a simple command line app that will print an emoji for you based on the holiday that you enter. Our new app will clearly rely heavily on the package that we just made.
Notice the use of the term ‘require’ to reference the module that we are going to use. This syntax is one of two major JS module importing paradigms that exist at the time of this writing (ES6 modules and CommonJS modules). What it does is imports the script that we wrote before into the app.js file at runtime.
If you try to run the program now
node index.js halloween
You will get the error below. That is because the dependency that we need (the holidaygenerator package) is not downloaded into our project yet. You will get an error from the require stack, telling you that the module is not found.
We need to import our node module. Hop into the terminal and run this command.
npm install --save holidaygenerator
You will see the code come down from the registry, including the edits to the file that you made! You will also see that the command has saved a reference to the module in our package.json. Now try the same command:
node index.js halloween// returns pumpkin emoji 🎃 as expected
// we've successfully imported the module from npmjs.org
Configuring and Additional Options
There are a few things that you will probably want to do after you publish your NPM package. I will list a few common configurations and briefly go over each below
- Move your code to github
- Add a license
- Release another version
- Change the permissions of your package
1. Move your code to Github
This is an obvious next step for your new package. If you want to collaborate with others around the module that you created, you will want to create a github repo to do so. It is tradition for the github repo with your package to also store the instructions for how to use the repo in a file called readme.md. You can get this done by taking the following steps:
- In your NPM module folder, create a file called readme.md
git initto initialize a git repo in your project
- Create the repo on github.com
- Push the code into that repo
2. Add a License
If you are planning on developing a piece of software for use by others you will need to also create a license, a legal document that tells other people who use the software what the limitations for their use are. For example, it may be illegal to download a copy of adobe illustrator for free and use it to make money: they will have specified the specific conditions in their software license. Visit this site by Github to find out how to add a license to your package, and which license is the best for your particular situation.
3. Release Another Version
If you try to push your file to npm again using npm publish, you will get the following error.
PUT https://registry.npmjs.org/holidaygenerator - You cannot publish over the previously published versions: 1.0.0.
The reason is that you’ve tried to overwrite your package with another version of the same package. NPM has a versioning system that is based off of Semvr, which I highly recommend reading, that specifies how you should version your software. So we’ll upgrade our version in package.json to:
and then publish again. You should see a success message. Now, to check that your version has changed you can go to your dependent application (our console app) and type
This command shows you what the versions of the packages that you have in your project are, compared to the latest versions. You can tell by the version number whether your software will be limited by the outdated package (for example if your package is outdated by 1–5 patches that should not be a problem, but if it is outdated by a major version then you’ll run into trouble).
To update your packages you can use the following npm command line command:
4. scope your package
You might have noticed that some packages have an @ symbol in front of the name. What’s that about?
By using the name @[some name]/[package] instead of just package, we create a package under the scope of our username. It’s called a scoped package. It allows us to use short names that might already be taken.
Pretty cool, huh?
Thanks for joining me on this journey. Happy Halloween in advance, everyone!