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

Node Webkit powered Dashboard application

Node Webkit Powered Dashboard app

In this post, we will be building a full fledged desktop application using node webkit and web technologies. We are going to build a dashboard app called myDashboard. The app will show the Weather report, Google Map, Flickr images and a Calendar. The final product would look like

Screen Shot 2014-07-20 at 3.47.12 pmScreen Shot 2014-07-20 at 3.46.14 pmScreen Shot 2014-07-20 at 3.48.13 pmScreen Shot 2014-07-20 at 3.48.33 pmScreen Shot 2014-07-20 at 3.47.55 pmYou can get the complete code here. The final installers are around 200MB, hence did not share the installer.

So, let us see how we can build this app.

Contents

Continue reading

Loving Google’s Web Starter Kit

For the past few days I have been totally digging Google’s Web Starter Kit. Yes, I have used Yeoman, Slush and other “One Stop – Best Practice” tools, but there is something about WSK that makes you want to use it as a Starter template kit for all your projects.

I have been going through the resources and I would recommend the following way to build a new app. Please feel free to share the way you develop too.

Phase I : What’s out there?

  • First, navigate to Google’s Web Fundamentals. You can find a list of resources on how to build a multi-device web site with a lot of awesome best practices.
  • Next Discover Multi-Device Tools and Install them as needed.

Continue reading

Your Portfolio Website with GitHub Pages

Your Portfolio with GitHub Pages

In this quick and dirty post, we will see how you can build a static Portfolio website for yourself. We will be leveraging the power of GitHub pages and the default sub-domain that you get when you create an account with GitHub.

First off, you need to be aware of what GitHub is. If you don’t, I recommend going through Git & GitHub for Beginners and if you not aware of GitHub pages, please go through Github Pages – Free Hosting as well.

A live demo of what we are going to build : http://arvindr21.github.io

Continue reading

Web Components – The Future Web

Web Components & Polymers – The Fabric of Future

This blog post is about Web Components. What they are, why do we need them and how to go about creating a few of our own. We will also look at the browser support, make sure our Web Components work everywhere with the help of polyfills like Polymer. And finally, we will be using Yeoman to scaffold a Polymer project and using Yeoman sub-generators to scaffold new Web Components.

So, let’s get rolling.

Contents

The Examples in this tutorial can be found at GitHub. Continue reading

Getting Started with Expressjs

Getting Started with Expressjs

This post is targeted at Express 3.x and *nix system, however the concepts are same across all OS for Express 3.x.

Windows users, please refer to the comment by acveer.

Once you are done with post, you can refer this post to see what has changed in Express 4.x

You can use Slush Express Generator to scaffold an Express 4 app, to be consistent across OS.

Express js

Express is a minimal and flexible node.js web application framework, providing a robust set of features for building single and multi-page, and hybrid web applications.

Expressjs is a server side framework, that takes care of handling requests and responses. It can use templating engines like Hogan (derived from HandleBars), Jade, ejs or CSS preprocessors like LESS, Stylus.

If you have worked with any web based Node projects earlier you must have seen a lot of them would be using Express. Because that is what Expres does to your Node app.

Contents

Continue reading

PhoneGap Quick Start

PhoneGap 3 Quick Start

PhoneGap Quick Start

PhoneGap is a free and open source framework that allows you to create mobile apps using standardized web APIs for the platforms you care about.

This blog post is a quick start tutorial on how to develop, build & deploy a native app using HTML5, CSS3, Javascript and PhoneGap. I am not going to explain what PhoneGap can/can’t do or rules for Native app development (may be I’ll write one later).

Contents

Continue reading

SASS and Foundation

SASS and Foundation

SCSS and Foundation

SASS SCSS and Foundation

As the name suggests we are going to take a dive into the world of CSS – Cascading Style Sheets. The reusable piece of documents that are served on every page, so our pages look alike & beautiful. The way I look at CSS, they are like the “make up” artists for our performers i.e. “HTML document”.

At the end of the day, a HTML document is a simple XML(EXtensible Markup Language), that is made up of tags (head, body, div etc..) and attributes (style, id, class) and intended to  carry data, not to display data. It is the responsibility of our browser engine to take that data and make HTML into something more meaningful i.e. DOM. DOM is a complete tl;dr post altogether.

Contents

Continue reading

Test Driven Development by Example

Test Driven Development by Example

In an earlier post, we have seen how to setup a framework/workspace that can be helpful to write easily testable Javascript code. Now we will dive into writing some code with the TDD approach. So lets get started.

Table of Contents

T.D.D. – Test Driven Development

Part 1 : Understand what TDD is all about. I ran into this amazing video by Rebecca Murphy. Where she explains as how Testable javascript needs to be written

A few excerpts from her presentation

Continue reading