Every developer has most likely used NPM packages at some point in their projects. But if you’ve never published your own package before it might seem like some scary, unknown, or complex thing. Let’s create a simple package and publish it to the NPM registry.
In order to publish a package to NPM you need to do three things:
- Create an NPM account.
- Create a package to publish.
- Publish the package to NPM.
Create an NPM Account
In order to publish a package on NPM, you need to create an account. It’s very simple to do. You just need to supply a username, e-mail address, and password.
Note: Your email address will be added to the metadata of packages that you publish, so it may be seen publicly.
Once you’ve created an account you should log in to it from the terminal. Run the following command to start the login process:
You will be prompted for your account details. Fill them in to finish the login process.
Creating a GitHub repository
Log in to your GitHub profile and create a new public repository. Give it a name like
ws-my-first-package and make sure to check the boxes to add a
Create a Package to Publish
The next step is to create an actual package to publish to the NPM registry. Let’s clone the GitHub project into a new folder and initialize a project from there.
Note: Package names on NPM need to be unique. Try to incorporate your initials into the project to make sure you’re using a unique name.
This will take you through a series of questions that sets up your package.json. You can skip questions that don’t make sense. Once you’ve finished with the prompt, you will have a package.json, file which is technically all you need to publish an NPM package. The package.json file has the following requirements.
It must contain the
"name" field contains your package’s name and must be lowercase and one word. The
name field may contain hyphens (
-) and underscores (
"version" field must be in the form
x.x.x and follow the semantic-versioning guidelines.
If you want to include package author information in the
"author" field, use the following format. The e-mail and website are both optional.
Your Name <firstname.lastname@example.org> (http://example.com)
Currently, the project is a bit bare. Let’s add some actual code to publish. Create an index.js file and add the following content:
This very simple function will add two numbers together and return the outcome.
The README.md File
A README file is meant to help other developers find, install and use your package. I strongly recommend you take some time to create a proper README for any serious package that will be published in the future.
The README file may include directions for installing, configuring, and using the code in your package. You can also include any other information a user may find helpful. The README file will be shown on the package page.
If you’ve followed along with the tutorial then your GitHub repository was created with a README file. If you didn’t check the box you can create a README.md file with the following command:
This is a standard Markdown file. You can find information on formatting markdown files here.
Publish the Package to NPM
Since NPM has the file tree of your project, it knows what packages are installed under node_modules. It uses this information to create a flat list of all NPM files in order to publish the package on the NPM registry.
Run the following command to start the publishing process:
This will take you through some prompts about where your package is stored and how to version it before finally publishing it to NPM.
That’s all there is to publishing your first NPM package! If you submitted the wrong name or version number, don’t worry; NPM can do this for you as well.
Testing the package
It’s simple to test the newly published package by simply creating a new project, installing the package from the registry, and calling the sum function.
Run the following commands:
Create an index.js file and import your module like this:
You can run the file with NodeJS using the following command:
Bonus tip: Use np for your package
It can become very cumbersome to manually test, bump versions and publish a package regularly. Especially, if you manage more than one package. The np package is a great help in managing your publishing process.
It automatically runs tests, bumps the version number, and publishes the package for you. Let’s try it out.
First, install np globally on your system:
Now, when you’re ready to publish a new version of your package. Run the np command in the terminal to get an interactive UI that guides you through the process.
Congratulations, you did it! You created your first NPM package, published it to the world, and verified it works by downloading it and testing your package.
I hope you learned something from this simple tutorial. If you have any thoughts, questions, feedback, or improvements, please let me know in the comments.