How to write and publish your first NPM package

August 16, 2020

We will write a library that helps to generate border-radius for HTML elements, we will name it "radiuswizard". This is just an example of a library that will give us the idea on how the NPM packages are written and published, so let’s start.

What you need to get started :

a- NPM account, if you don’t have it, go to https://www.npmjs.com/signup and sign up. In order to publish your package, you will have to verify your email, so make sure to do that, also, remember the username and password because we will use them in a moment..

b- Go to your console and run npm adduser then enter your NPM account’s informations.

1- Writing the NPM package :

we will create a folder called “radiuswizard” for our project (you can call it whatever you want).

mkdir radiuswizard && cd radiuswizard

Open this project in your code editor and let’s start writing our package.

we will make a new file ‘index.js’ which will contain our JavaScript function :

function radiuswizard(options) { let elements = document.querySelectorAll('.radiuswizard') elements.forEach(el => { if (options.circle) { el.style.borderRadius = '50%' } else { el.style.borderRadius = `25px` } }) } module.exports.radiuswizard = radiuswizard

Let’s break down what’s happening in this file, To start with, our radiuswizard function accepts an options object , our elements variable represents all the elements that have the .radiuswizard class.

If the user passes the circle as an option, the elements will get a border-radius of 50%, else it’s 25px as a default value.

Of course before we publish our package, we need to give details about it, for that let’s add a README.md file :

# Description npm package for adding border-radius to your elements. # Installation `npm i radiuswizard --save` ``` import {radiuswizard} from 'radiuswizard'; radiuswizard({ circle: false }) ``` ## Options radiuswizard supports only one option: - _circle_ - _boolean_ (Defaults to false)

we have three sections in this file, the first one for describing the usage of this package, the second to tell users how they can install it, the last one is for the options, we tell the user that this package supports only one option which is boolean.

… And we finished writing the package 😁

2- Getting ready to publish our npm package

In order to publish our package, we need to deploy this project to Github.

We will create a new public repository with this name ‘radiuswizard’, check this : Github-docs if that's your first time making a repository on Github.

Then run these commands in the console :

git init git add . git remote add origin git@github.com:LaasriNadia/radiuswizard.git //make sure to replace LaasriNadia by your Github username git push -u origin master

One more step before publishing the package is to add a package.json file to our project. For that we run :

npm init

it will ask you some questions, these are the ones we will answer ( Press Enter to skip the other questions ) :

description : border-radius for your elements

keywords : border-radius

author : put your name here

We are now ready to publish our NPM package. 🚀

3- Publishing our NPM package

The only thing we have to do in order to publish our package is to run :

npm publish

If you get this error :

40 Forbidden - PUT https://registry.npmjs.org/radiuswizard - radiuswizard cannot be republished until 24 hours have passed.

It’s because we are using the same name for this package, so go back to package.json file and change the name value of this package then run npm publish again.

To make sure your package is published go to npmjs.com and search for your package’s name. You should get something like this : https://www.npmjs.com/package/radiuswizard

BONUS

We will now take the role of the user and use the package we just created. Run:

mkdir radiususage && cd radiususage npm init -y

Let’s make an index.html file in this directory :

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta http-equiv="X-UA-Compatible" content="ie=edge"> <title>Document</title> </head> <body> <img src="https://via.placeholder.com/150" alt="borderRadius150" class="radiuswizard"> <script src="./index.js"></script> </body> </html>

We added an image and we give it a class of radiuswizard.

Let’s add an index.js file

import { radiuswizard } from 'radiuswizard'; radiuswizard({ circle: false })

Let’s now install our package, run :

npm i radiuswizard --save

we are now ready to test our package.

We need a javascript bundler, for that we will use parcel, easy and requires zero configuration, if you don’t have it on your machine, install it by running this :

npm i parcel -g

when the installation is finished. run the development server :

parcel index.html

Now open http://localhost:1234/ in the browser:

That’s what we see :

radius

Yaaay!! It's working, our image has a border-radius of 25px as we specified in our package. 🤩

Let’s try the circle option, go back to index.js file and give the circle a true value instead of false :

import { radiuswizard } from 'radiuswizard'; radiuswizard({ circle: true })

Now the border-radius of 50% is applied to our image:

radius

Everything is working as expected. 🥳

Congratulations on writing and publishing your first NPM package ✅

Comments