NPM behind the scenes and publish guide
Tags: node, npm, javascript, opensource
Published: 2018-11-21 13:56:58

---
title: NPM behind the scenes and publish guide
published: true
description: A quick guide explaining how NPM works behind the scenes and how to publish and update your packages in npmjs.org
tags: node.js, npm, javascript, opensource
---

<p>Lately I've found myself in a situation when I have to reuse some of my code in different projects and I've ended up just copy pasting functions or entire files from one project to another. This is not very practical as I have to browse between projects and it always takes a while until I found what I'm looking for. I always thought about publishing those packages in NPM but ended up not doing it... until now.</p><p> In this article I'll explain how NPM woks behind the scenes, and the different ways to publish your own JS modules so you can reuse them in other projects or just share them.</p><h2>NPM behind the scenes</h2><p>NPM comes packaged with Node so they'll be installed at the same time. It's used to initialise Node.js packages (it generates a package.json with&nbsp;<strong><em>$npm init</em></strong>) and to manage dependencies (eg. <em><strong>$npm install express</strong></em>), similar to Composer for PHP.&nbsp;</p><p>You've probably used NPM a ton of times to install packages which are served from&nbsp;<a href="https://registry.npmjs.org/" title="NPM public registry" target="_blank" style="font-size: 1rem; text-decoration-line: underline; background-color: rgb(254, 254, 254);">npmjs.com</a><span style="font-size: 1rem;">&nbsp;but, how do they relate? The </span><strong style="font-size: 1rem;">registry</strong><span style="font-size: 1rem;">. You can think of the registry as a yellow pages. It's an index for all the packages available and, by default, it uses the public registry from </span><a href="https://registry.npmjs.org" title="NPM public registry" target="_blank" style="background-color: rgb(254, 254, 254); font-size: 1rem;">npmjs.com</a><span style="font-size: 1rem;">, but you can&nbsp; modify it and point it to any registry you want, like a private registry. This is usually the case in large companies that have their own registry where they publish internal packages.</span></p><p>Inside the registry packages can be published publicly or as part of a&nbsp;<strong>scope</strong>, which are used to group related packages. The scope can be an organisation or even your username. Scoped packages are named with the following convention: @scope/package-name, and are published privately by default so you'll have to manually open them to the public or manage who can access to it.</p><p>That's a quick overview of NPM works behind the scenes. If you want to know more details they have a <a href="https://docs.npmjs.com/" title="NPM documentation" target="_blank">very good documentation</a>. Now let's move on and see how to publish your own packages.</p><br><h2>Publish your package in NPM</h2><p>First thing we need is an account so if you don't have one, go ahead and register in <a href="http://www.npmjs.com" title="NPM main page" target="_blank">npmjs.com</a>&nbsp;. We also need a package to publish. For this example I'm going to publish a small package that I think I'm going to use in multiple projects. It contains an express middleware to validate if an API request object has a valid authentication token (JWT). The code of this package can be found in the <strong><a href="https://gitlab.com/uF4No/isjwted" title="isjwted in Gitlab" target="_blank">following repo</a> </strong>and... it's also available<strong> <a href="https://www.npmjs.com/package/isjwted" title="isjwted in NPM" target="_blank">in NPM</a>.</strong></p><p>Before publishing your code in NPM, I recommend you to:</p><ul><li>Have your code in a repository (GitHub, GitLab....)<br></li><li>Include a Readme.md with as much detail as you can, even with examples of how to use your package.<br></li><li>Include tests<br></li></ul><p>Once we have our code ready we can push it to NPM. Open a terminal, navigate to your project folder and authenticate in NPM using <strong style="font-style: italic;">$npm login .&nbsp;</strong>To make sure you are authenticated, type <strong style="font-style: italic;">$npm whoami</strong> which should return your username.</p><p style="text-align: center; "><img src="http://www.antonioufano.com/image_uploads/NPM_Auth.png" alt="NPM Auth check"><br></p><p>Now, to publish your package, you just have to run <strong><em>$npm publish</em></strong> . Your package will be published in NPM with the name and version from the package.json file so those fields are mandatory. Try to use a descriptive name for your package but make sure it's not already in use. If your package name is not available you'll get the following error "<em>You do not have permission to publish "hello-world". Are you logged in as the correct user?</em>" so better check if the name of your package is available first.</p><p>If you are correctly logged in and the name of your package is available your package should appear in your npmjs.com profile and other users will be able to install it via <em><strong>$npm install your-package-name</strong></em>.</p><p style="text-align: center; "><img src="http://www.antonioufano.com/image_uploads/NPM_publish.png" alt="NPM publish"><br></p><h3>Updating your packages</h3><p>You'll probably&nbsp; need to update your package to fix issues, vulnerabilities, update dependencies or even add new features. You can do this in two different ways.</p><p><span style="font-size: 1rem;">Automatic patch: You can rely on NPM to update the version number of your package depending on the type of change you're introducing: a small fix, a backwards compatible new feature or a non backwards compatible change. There are different commands for each:&nbsp;</span></p><ul><li><span style="font-size: 1rem;"><strong style="font-style: italic;">$npm version patch</strong>&nbsp;</span><span style="font-size: 1rem;">will update the last digit of your version (eg. v1.0.0 -&gt; v.1.0.1)</span><br></li><li><strong style="font-size: 1rem; font-style: italic;"><em>$npm version minor</em></strong><span style="font-size: 1rem; font-style: italic;"> </span><span style="font-size: 1rem;">will update the second digit (eg. from v1.0.0 --&gt; v.1.1.0</span><span style="font-size: 1rem; font-style: italic;">)</span><br></li><li><strong style="font-size: 1rem; font-style: italic;"><em>$npm version major </em></strong><span style="font-size: 1rem;">will update the first digit (eg. from v1.0.0 --&gt; v2.0.0)</span></li></ul><p><span style="font-size: 1rem;">Manually: you'll have to update the version number in your package.json file to whatever version you want. I'd try to follow the same convention explained above.</span></p><p><span style="font-size: 1rem;">In both cases, once your version number is updated, you'll have to republish your package with&nbsp;</span><span style="font-size: 1rem; font-weight: bolder;"><em>$npm publish</em></span><span style="font-size: 1rem;">&nbsp;</span><span style="font-size: 1rem;">. Note that if you try to publish a modified package with the same version number you'll get an error.</span><br></p><p style="text-align: center;"><img src="http://www.antonioufano.com/image_uploads/NPM_version.png" alt="NPM update package"><br></p><br><h2 style="font-family: " open="" sans",="" sans-serif;="" color:="" rgb(33,="" 37,="" 41);"="">Conclusion</h2><p>As you can see, publishing your packages in the public registry of NPM is very easy, you can do it with a few commands. In addition NPM allows you to use scopes to group your packages and even keep them private. So if you have a piece of code you think you can reuse or that may be useful to someone, go ahead and publish it! you never know when it might help solve a problem and you can even include those packages as part of your CV :)&nbsp;</p><p>And now that you're here, feel free to install and try&nbsp;<a href="https://www.npmjs.com/package/isjwted" title="isjwted package in NPM" target="_blank" style="font-weight: bold;">isjwted</a>. It may help you if you are working in a express based application and you need to validate the presence of a valid token in your requests. Feedback is more than welcome!</p><p>Happy coding!</p>
<p>This article was originally posted in <a href="http://www.antonioufano.com" target="_blank">my website</a>. Feel free to pay me a visit and give me some feedback in the <a href="http://www.antonioufano.com/contact" target="_blank">contact</a> section.<p>