Setting up an NPM-based development environment

When you are working on a more complex data visualization project that requires the use of a number of JavaScript libraries, the simple solution we discussed before might become a bit clumsy and unwieldy. In this section, we will demonstrate an improved setup using Node Packaged Modules (NPM)—a de facto JavaScript library repository management system. If you are as impatient as me and want to get to the meaty part of the book—the recipes—you can safely skip this section and come back when you need to set up a more production-ready environment for your project.

Getting Ready

Before we start please make sure you have NPM properly installed. NPM comes as part of the Node.js installation. You can download Node.js from http://nodejs.org/download/. Select the correct Node.js binary build for your OS. Once installed the npm command will become available in your terminal console.

> npm -v 
1.2.14

The preceding command prints out the version number of your NPM client indicating the installation is successful.

How to do it...

With NPM installed, now we can create a package descriptor file to automate some of the manual setup steps.

1. First, under your project folder, create a file named package.json containing the following code:

   {
     "name": "d3-project-template",
     "version": "0.1.0",
     "description": "Ready to go d3 data visualization project template",
     "keywords": [
       "data visualization",
       "d3"
     ],
     "homepage": "<project home page>",
     "author": {
       "name": "<your name>",
       "url": "<your url>"
     },
     "repository": {
       "type": "git",
       "url": "<source repo url>"
     },
     "dependencies": {
         "d3":"3.x"
     },
     "devDependencies": {
         "uglify-js": "2.x"
     }
   }

2. Once the package.json file is defined, you can simply run:

   > npm install

How it works...

Most of the fields in the package.json file are for informational purpose only, such as the name, description, homepage, author, and the repository. The name and version field will be used if you decide to publish your library into an NPM repository in the future. What we really care about, at this point, is the dependencies and devDependencies fields.

• The dependencies field describes the runtime library dependencies that your project has, meaning the libraries your project needs to run properly in a browser. In this simple example we only have one dependency on d3. d3 is the name that D3 library is published under in the NPM repository. The version number 3.x signifies that this project is compatible with any version 3 releases, and NPM should retrieve the latest stable version 3 build to satisfy this dependency.

  Tip

  D3 is a self-sufficient library with zero external runtime dependency. However, this does not mean that it cannot work with other popular JavaScript libraries. I regularly use D3 with other libraries to make my job easier, for example, JQuery, Zepto.js, Underscore.js, and Backbone.js.

• The devDependencies field describes development time (compile time) library dependencies. What this means is that, libraries specified under this category are only required in order to build this project, and not required for running your JavaScript project.

Note

Detailed NPM package JSON file documentation can be found at https://npmjs.org/doc/json.html.

Executing the npm install command will automatically trigger NPM to download all dependencies that your project requires including your dependencies' dependencies recursively. All dependency libraries will be downloaded into node_modules folder under your project root folder. When this is done you can just simply create your HTML file as it has been shown in the previous recipe, and load your D3 JavaScript library directly from node_modules/d3/d3.js.

The source code for this recipe with an automated build script can be found at https://github.com/NickQiZhu/d3-cookbook/tree/master/src/chapter1/npm-dev-env.

Relying on NPM is a simple and yet effective way to save you from all the trouble of downloading JavaScript libraries manually and the constant need of keeping them up-to-date. However, an astute reader might have already noticed that with this power we can easily push our environment setup to the next level. Imagine if you are building a large visualization project where thousands of lines of JavaScript code will be created, obviously our simple setup described here is no longer sufficient. However modular JavaScript development by itself can fill an entire book; therefore we are not going to try to cover this topic since our focus is on data visualization and D3. If you are interested please refer the source code for this recipe where it is demonstrated how a more modular approach can be implemented on top of what we described here with a simple automated build script. In later chapters, when unit test related recipes are discussed, we will expand the coverage on this topic to show how our setup can be enhanced to run automated unit tests.

There's more...

Though in previous sections, it was mentioned that you can just open the HTML page that you have created using your browser to view your visualization result directly, this approach does have its limitations. This simple approach stops working once we need to load data from separate data file (this is what we will do in later chapters and it is also the most likely case in your daily working environment) due to the browser's built-in security policy. To get around this security constraint it is highly recommended that you set up a local HTTP server so your HTML page and the data file can be served from this server instead of loaded from file system directly.

Setup a local HTTP server

There are probably a dozen ways to set up an HTTP server on your computer based on which operating system you use and which software package you decide to use to act as an HTTP server. Here I will attempt to cover some of the most popular setups.

Python Simple HTTP Server

This is my favorite for development and fast prototyping. If you have Python installed on your OS, which is usually the case with any Unix/Linux/Mac OS distro, then you can simply type this command in your terminal:

> python –m SimpleHTTPServer 8888

Or with newer Python distribution:

> python –m http.server 

This little python program will launch an HTTP server and start serving any file right from the folder where this program is launched. This is by far the easiest way to get an HTTP server running on any OS.

Note

If you don't have python installed on your computer yet, you can get it from http://www.python.org/getit/. It works on all modern OS including Windows, Linux and Mac.

Node.js HTTP Server

If you have Node.js installed, perhaps as part of the development environment setup exercise we did in the previous section, then you can simply install the http-server module. Similar to Python Simple HTTP Server, this module will allow you to launch a lightweight HTTP server from any folder and starting serving pages right away.

First install the http-server module:

> npm install http-server –g

The -g option in this command will install http-server module globally so it will become available in your command line terminal automatically. Once this is done, then you can launch the server from any folder you are in by simply issuing the following command:

> http-server .

This command will launch a Node.js powered HTTP server on the default port 8080 or if you want you can use the –p option to provide a custom port number for it.

Tip

If you are running the npm install command on Linux/Unix/Mac OS, you will need to run the command in sudo mode or as root in order to use the –g global installation option.