Publishing a package on npm (which stands for Node Package Manager) is an excellent way to share reusable code with the open-source developer community. Whether you've created a simple library to help speed things up or a powerful framework or tool, publishing your package will make it accessible to thousands of developers around the world.
Let's explore the process of publishing an npm package using Node.js and npm step by step.
An open-source project is a project freely shared with the entire developer community: its use is free, and generally anyone can contribute to it.
Prerequisites
Before starting, there are a few prerequisites and tools you need to have on your computer:
- Install Node.js - You must have Node.js on your computer to create an npm package. Click here to install it.
- Have an NPM account - To create a package, you must have your own account created on npmjs.com
- Install Git (optional) - If you want to create different versions of your package or share it on a GitHub repository, you must also have Git installed on your computer.
Step 1: Create a New Node.js Project
Start by creating a directory for your new package. Then, initialize a Node.js project using the npm init command:
mkdir my-believemy-package
cd my-believemy-package
npm initHere's what we're doing:
mkdir- We create a folder "my-believemy-package"cd- We go into our foldernpm init- We initialize NPM. This command asks a bunch of questions like the package name, version, a short description, and even your first and last name. But you can also accept the default values by simply pressingEnter.
Normally, our new package.json file should now be generated in our folder. It contains the information for our future package.
Step 2: Create the Package Code
Now that our project is initialized, let's make sure our package does something! 😬
Let's say our package allows adding two numbers:
// index.js
function addition(a, b) {
return a + b;
}
module.exports = addition;We simply created a function before adding an instruction that allows us to export it with module.exports.
Step 3: Prepare the Package
Before offering a package, it's crucial to check the information in our package.json file. In particular, verify these three pieces of information:
main- This field must point to the entry file of your module, hereindex.js.keywords- This field allows you to add keywords to make your package easier to find on npm.repository(optional) - If you use GitHub to store your files, just specify the URL of your repository (whether it's GitHub or GitLab of course 😉).
For example:
{
"name": "my-believemy-package",
"version": "1.0.0",
"description": "Just a package that adds two numbers",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "Believemy",
"license": "MIT",
"keywords": ["additions", "mathematics", "believemy"],
"repository": {
"type": "git",
"url": "put your url here"
}
}
Step 4 - Test the Package Locally
Before publishing your package, you can test it by using it locally. To try, simply create another Node.js project to install your package locally using a symbolic link.
A symbolic link (called a symlink) is a kind of shortcut to another file or folder in the file system. Just think of a symbolic link as adding a label to something, this something being a folder or a file.
This allows us to call it much more easily.
For example, instead of calling a specific file on our computer like this:
We can create a symbolic link to give it a new label:
Here, ln -s asks to create a new label (a symbolic link) for the resource /path while adding my-folder as a new shortcut.
So we can do:
In the Package Folder
In your package folder, here's what you need to type in your terminal:
npm linkThis command creates a new symbolic link between a local package and a project with Node.js. Generally, it's used to test a package locally: that's exactly what we're doing! 😉
In the Test Project
Then, in your test project, type:
npm link my-believemy-packageOur new package is now linked to our test project!
Step 5 - Log in to NPM
If you're not already logged in to npm from the command line, you need to log in using the following command:
npm login
Step 6 - Publish the Package ✨
Now that everything is in place, you're ready to publish your package! Use the following command to publish it to the npm registry:
npm publishYou can now find your brand new package by searching for its name on npmjs.com.
If you have a name conflict: this means the name you chose for your package is already taken. In this situation, just modify the name field in your package.json file and type the npm publish command again.
Step 7 - Update a Package
If you modify your package, you will also need to change the version in your package.json file before publishing the update. Be careful because npm follows versions using semantic versioning (semver).
For example:
- For a bug fix - You must increment the last version number (example: 1.0.1)
- For a new feature that doesn't break anything (non-breaking) - You must increment the middle number (example: 1.1.0)
- For a significant change (breaking) - You must increment the first number (example: 2.0.0)
Then, publish the new version by running:
npm version patch
npm publishIt's also possible to replace patch with:
minor- for a minor modificationmajor- for a major modification
Step 8 - Make a Package Private (bonus)
If you don't want your package to be public and accessible to everyone, you can make it private by adding the following line in your package.json file:
"private": trueThis instruction prevents the package from being published in npm searches (also called registry).
Another possibility is to specify during the publication of your package on npm that you do not want it to be public:
Making your package private comes at a cost: $7 per month.
Conclusion
You now know how to publish an npm package with Node.js!
Publishing an npm package is an excellent way to share your work: as they say, one must know how to give back to the community what the community provides with all its open-source tools.
And if you want to go further: learn how to use Git with our complete training.