Build & Publish a Node Package Module (NPM)

In this post, we are going to build and publish a Node Package Module (NPM). The module we are going to build is a simple utility which will take a  Web supported color name as an argument and spits out the HEX & RGB values for the same. We are going to use a Test Driven Development (TDD) style of coding for building this module.

I have taken the color names from htmlcolorcodes.com – Thanks to them!

Before we get started, here is a quick preview of the CLI version in action

The story behind rebeccapurple. RIP Rebecca Meyer.

Getting Started

Below are the steps we are going to follow

  1. Setup Yeoman
  2. Install Generator
  3. TDD Colorcode
  4. Validate Code Coverage
  5. Push to Github
  6. Setup Travis CI
  7. Setup Coverall
  8. Publish to NPM

Setup Yeoman

If you are new to Yeoman, Yeoman is

What is Yeoman?

Ripping off from yeoman.io

Yeoman helps you to kickstart new projects, prescribing best practices and tools to help you stay productive.

To do so, we provide a generator ecosystem. A generator is basically a plugin that can be run with the yo command to scaffold complete projects or useful parts.

Through our official Generators, we promote the “Yeoman workflow”. This workflow is a robust and opinionated client-side stack, comprising tools and frameworks that can help developers quickly build beautiful web applications. We take care of providing everything needed to get started without any of the normal headaches associated with a manual setup.

With a modular architecture that can scale out of the box, we leverage the success and lessons learned from several open-source communities to ensure the stack developers use is as intelligent as possible.

As firm believers in good documentation and well thought out build processes, Yeoman includes support for linting, testing, minification and much more, so developers can focus on solutions rather than worrying about the little things.

So ya, Yeoman is like your File > New > NPM project | fill the project information and boom! A NPM project gets generated; but from command line.

To install Yeoman globally, run

And to validate, run

Install Node.js

Before we go further, make sure you have Node.js installed on your machine. You can follow this post Hello Node for same. I am using the following versions

generator-np

In this post, we are going to use a Yeoman generator named generator-np to scaffold our base for building the NPM. To install the generator globally, run

Once the installation is done, we are good to scaffold our app

Scaffold color2code

Anywhere on your machine, create a folder named color2code  and open a new terminal/prompt there. Now, run

And you can answer the questions as shown below

This will take a moment to complete scaffolding.

Once the project scaffolded, we should see something like

In this project, we are going to follow a Test Driven Development approach. We will first update the  test/index.js  file with all possible scenarios and then get started with the code.

Next, we are going to work in src  folder to update the cli.js  and the  lib/index.js  files.

Before we get started, let’s quickly look at the solution.

Color2Code Solution

The app we are going to build is a simple utility that takes a popular web supported color names and spits out the RGB and HEX values of the same.

We are going to maintain a collection of all the web supported colors and their HEX values. And in our code, we are going to read color name and fetch the HEX value. We then use the HEX value to generate the RGB version of the same.

Sounds simple right?

So, let’s see how to work with this solution & build a NPM.

Update project configuration

I have made a few changes to the project so that things are a bit more easy to manage.

Open  .eslintrc  and make the changes to the properties shown below

Next, we are going to update  package.json  as highlighted below

Finally, update  .travis.yml as shown below

That is all!

Test Driven Development – TDD

To work with the code base we have just scaffolded, we are going to use TDD or Test Driven Development. We are going to write the test cases first and then develop our code.

TDD is not for the weak hearted. Seeing your application fail even before writing a single line of code takes courage.

You can read more about TDD here: Test Driven Development by Example

Write Test Cases

To get started, we are going to write the test cases first and see our app fail and then start making the required changes to our code to fix it.

Open  test/index.js and update it as shown below

The above file outlines 5 scenarios

  1. If there is no color name provided to our NPM
  2. If one color name is provided to our NPM
  3. If more than one color names are provided to our NPM
  4. If an invalid color name is provided to our NPM
  5. If an invalid color name is provided along with valid color names to our NPM

The code we are writing should satisfy the above 5 scenarios.

Now, let’s run the NPM and see it fail.

Run the NPM

We are going to use nodemon to watch our app for changes and rebuild our application.

To install nodemon, run

Once nodemon is installed, from inside color2code  folder, run

If the command ran successfully, we should see an error blob stating that tests have failed.

Yay! we did it.

Now, let’s get cracking on fixing these cases.

PS: Keep the nodemon running in the terminal/prompt. As we keep making changes and saving files, the tests will be executed again.

Develop the NPM

First, we are going to get a dump of Web colors. Thanks to htmlcolorcodes.com, we have list of 148 color names.

Create a file named  colors.json inside  src/lib folder and update it as shown below

Save the file and you should see that nodemon  has detected changes to the src  folder and is running the prepare  task again. The tests are still failing.

Next, inside  src/lib folder, create a file named  utils.js and update it as shown below

On Line 1, we have required the colors hash.  hexToRGB() takes a HEX code and returns the RGB hash for the same.  processColor() takes in the color name and returns the final result.

Save the file and still the tests do not pass.

Awesome! let’s continue

Update  src/lib/index.js as shown below

Here we are processing the options and responding accordingly.

Save the file and Boom!

All the tests pass! And our NPM works!

Now, we will udpate  src/cli.js as follows

This concludes our development.

Simulate NPM install & Test

If you would like to simulate an NPM global install and test your app before publishing, you can do so by running the below command from inside the  color2code folder

And we should see something like

And from anywhere on your machine you can run

Awesome right!

Code Coverage

We have written code and we have written test cases. Now, let’s take a look at the code coverage.

From inside  color2code folder, run

And we should see something like

You can also open  coverage/index.html to view the report in the browser. It should look something like this

So we are good to move our code to Github.

Push color2code to Github

You can push your fresh NPM to git to maintain it and let other people look-see/contribute to your code. For that we will follow the below steps

  1. Create a new Github repo: https://github.com/new
  2. Run the following commands

PS: Update your repo URL as applicable

Voila! The code is deployed to Github. You can checkout my code here: arvindr21/color2code

Now that this is done, let’s setup Travis CI and Coveralls.

Setup Travis CI

Now that the repo is setup in Github, we will have a CI system in place. A Continuous Integration System keeps a tab on your repo for new changes and runs test cases on new changes and let’s you know if anything is broken.

Travis CI is a popular open source solution. You can read more about Travis CI here. We are going to use the same for managing our NPM.

If you open your Github repo, at the top of your readme, you should find a section as below

Click on “build | unknown” and you should be taken to Travis CI. In Travis CI, you should see a page like below

Activate repository.

From next time onwards when ever there is a push to the repo, the CI will kick in and check if the build has passed.

Before we trigger a build, we will setup Coveralls.

Setup coveralls

Quoting from coveralls.io/continuous-integration

Coveralls takes the build data from whichever CI service your project uses, parses it, and provides constant updates and statistics on your projects’ code coverage to show you how coverage has changed with the new build, and what isn’t covered by tests. Coveralls even breaks down the test coverage on a file by file basis. You can see the relevant coverage, covered and missed lines, and the hits per line for each file, as well as quickly browse through individuals files that have changed in a new commit, and see exactly what changed in the build coverage.

Back to our repo and at the top of readme, click on “coverage | unknown” and you should be redirected to coveralls.io. Sign in and Click on the “+” sign in the menu on left hand side and search your repo here. Once you find it, enable coveralls for this repo.

And that is all, we are done.

Trigger Build

Now, let’s go back to Travis and trigger build from “More options” menu on the right hand side. And you should be shown a popup, fill it as applicable – trigger custom build

And once the build is completed, you should see something like this

Sweet right! Our NPM works from versions 4 to 10. Yay!!

This trigger will happen automagically when ever there is a new commit/Pull request.

The final step if build passes is to update coveralls. If we navigate to coveralls for our repo, we should see something like

Travis arvindr21/color2code

We have a code coverage of 90%, which is good, considering we have only written few lines code.

We can also find out which files has what amount of coverage, as shown below

You can drill down further to analyse the issues.

With this we are done with our CI and Code coverage setup. If we go back to our Repo’s readme file, we should now see

Now, we are going to publish the color2code to npmjs.com.

Publish color2code to NPM

To push color2code to NPM, we need to have an account with npmjs.com. Once you have signed up and activated your account, you can login to the same from your command prompt/terminal.

Run

Once logged in, make sure you are at the root of  color2code folder and run

And boom your color2code  NPM is published.

If you get an error, which mostly will happen because you have used the same name as mine – color2code. You need to use another name for your module in package.json  file and then try publishing.

Your NPM is published. Navigate to npmjs.com/package/color2code to see the module we have just built.

With this our repo badges would look like

Hope you have learned how to build, publish and manage your own NPM!


Thanks for reading! Do comment.
@arvindr21