How To Publish Your First NPM Package in Just 15 Minutes

A step-by-step guide to publishing an open-source package to the JavaScript ecosystem

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:

  1. Create an NPM account.
  2. Create a package to publish.
  3. 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:

npm login
view raw npm-login.bash hosted with ❤ by GitHub

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 README and .gitignore file.

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.

cd projects
git clone git@github.com:YourUserName/ws-my-first-package.git
cd ws-my-first-package
npm init

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" and "version" fields.

The "name" field contains your package’s name and must be lowercase and one word. The name field may contain hyphens (-) and underscores (_).

The "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 <email@example.com> (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:

function sum(num1, num2) {
return num1 + num2;
}
module.exports = sum;
view raw index.js hosted with ❤ by GitHub

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:

touch readme.md

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:

npm publish

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:

mkdir test-first-npm-package
cd test-first-npm-package
npm install ws-first-npm-package
view raw testing.sh hosted with ❤ by GitHub

Create an index.js file and import your module like this:

const sum = require('ws-first-npm-package');
console.log(sum(4, 5));
view raw index.js hosted with ❤ by GitHub

You can run the file with NodeJS using the following command:

node index.js
view raw run.sh hosted with ❤ by GitHub

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:

npm install np -g
view raw install-np.bash hosted with ❤ by GitHub

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.

np
view raw np.sh hosted with ❤ by GitHub

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.

Conclusion

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.

If you’d like to support me, you could follow me on Twitterbuy me a Ko-fi or subscribe to Medium through my link (affiliate).

Happy Coding!

LEAVE A REPLY

Your email address will not be published. Required fields are marked *