Installing Node and community add-ons - Node.js in Action (2014)

Node.js in Action (2014)

Appendix A. Installing Node and community add-ons

Node is easy to install on most operating systems. Node can either be installed using conventional application installers or by using the command line. Command-line installation is easy on OS X and Linux, but it’s not recommended for Windows.

To help you get started, the following sections detail the Node installation on OS X, Windows, and Linux operating systems. The last section in this appendix explains how you can use the Node Package Manager (npm) to find and install useful add-ons.

A.1. OS X setup

Installing Node on OS X is quite straightforward. The official installer (http://nodejs.org/#download), shown in figure A.1, provides an easy way to install a precompiled version of Node and npm.

Figure A.1. The official Node installer for OS X

If you’d rather install from source, you can either use a tool called Homebrew (http://mxcl.github.com/homebrew/), which automates installation from source, or you can manually install from source. Installing Node from source on OS X, however, requires you to have Xcode developer tools installed.

Xcode

If you don’t have Xcode installed, you can download Xcode from Apple’s website (http://developer.apple.com/downloads/). You’ll have to register with Apple as a developer, which is free, to access the download page. The full Xcode installation is a large download (approximately 4 GB), so as an alternative Apple also offers Command Line Tools for Xcode, which is available for download on the same web page and gives you the minimal functionality needed to compile Node and other open source software projects.

To quickly check if you have Xcode, you can start the Terminal application and run the command xcodebuild. If you have Xcode installed, you should get an error indicating that your current directory “does not contain an Xcode project.”

Either method requires entering OS X’s command-line interface by running the Terminal application that is usually found in the Utilities folder in the main Applications folder.

If you’re compiling from source, see section A.4 for the necessary steps.

A.1.1. Installation with Homebrew

An easy way to install Node on OS X is by using Homebrew, an application for managing the installation of open source software.

Install Homebrew by entering the following into the command line:

ruby -e "$(curl -fsSkL raw.github.com/mxcl/homebrew/go)"

Once Homebrew is installed, you can install Node by entering the following:

brew install node

As Homebrew compiles code, you’ll see a lot of text scroll by. The text is information related to the compiling process and can be ignored.

A.2. Windows setup

Node can be most easily installed on Windows by using the official standalone installer (http://nodejs.org/#download). After installing, you’ll be able to run Node and npm from the Windows command line.

An alternative way to install Node on Windows involves compiling it from source code. This is more complicated and requires the use of a project called Cygwin, which provides a Unix-compatible environment. You’ll likely want to avoid using Node through Cygwin unless you’re trying to use modules that won’t otherwise work on Windows or need to be compiled, such as some database driver modules.

To install Cygwin, navigate to the Cygwin installer download link in your web browser (http://cygwin.com/install.html) and download setup.exe. Double-click setup.exe to start installation, and then click Next repeatedly to select the default options until you reach the Choose a Download Site step. Select any of the download sites from the list, and click Next. If you see a warning about Cygwin being a major release, click OK to continue.

You should now see Cygwin’s package selector, as shown in figure A.2.

Figure A.2. Cygwin’s package selector allows you to select open source software that will be installed on your system.

You’ll use this selector to pick the software functionality you’d like installed in your Unix-like environment (see table A.1 for a list of Node development–related packages to install).

Table A.1. Cygwin packages needed to run Node

Category

Package

devel

gcc4-g++

devel

git

devel

make

devel

openssl-devel

devel

pkg-config

devel

zlib-devel

net

inetutils

python

python

web

wget

Once you’ve selected the packages, click Next.

You’ll then see a list of packages that the ones you’ve selected depend on. You need to install those as well, so click Next again to accept them. Cygwin will now download the packages you need. Once the download has completed, click Finish.

Start Cygwin by clicking the desktop icon or Start menu item. You’ll be presented with a command-line prompt. You then can compile Node (see section A.4 for the necessary steps).

A.3. Linux setup

Installing Node on Linux is usually painless. We’ll run through installations from source code on two popular Linux distributions: Ubuntu and CentOS. Node is also available through package managers on a number of distributions, and there are other installation instructions on GitHub:https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager.

A.3.1. Ubuntu installation prerequisites

Before installing Node on Ubuntu, you’ll need to install prerequisite packages. This is done on Ubuntu 11.04 or later using a single command:

sudo apt-get install build-essential libssl-dev

Sudo

The sudo command is used to perform another command as “superuser” (also referred to as “root”). Sudo is often used during software installation because files need to be placed in protected areas of the filesystem, and the superuser can access any file on the system regardless of file permissions.

A.3.2. CentOS installation prerequisites

Before installing Node on CentOS, you’ll need to install prerequisite packages. This is done on CentOS 5 using the following commands:

sudo yum groupinstall 'Development Tools'

sudo yum install openssl-devel

Now that you’ve installed the prerequisites, you can move on to compiling Node.

A.4. Compiling Node

Compiling Node involves the same steps on all operating systems.

On the command line, you first enter the following command to create a temporary folder into which you’ll download the Node source code:

mkdir tmp

Next, you navigate into the directory created in the previous step:

cd tmp

You now enter the following command:

curl -O http://nodejs.org/dist/node-latest.tar.gz

Next, you’ll see text indicating the download progress. Once progress reaches 100 percent, you’re returned to the command prompt. Enter the following command to decompress the file you received:

tar zxvf node-latest.tar.gz

You should then see a lot of output scroll past, and you’ll be returned to the command prompt. At the prompt, enter the following command to list the files in the current folder, which should include the name of the directory you just decompressed:

ls

Next, enter the following command to move into this directory:

cd node-v*

You’re now in the directory containing Node’s source code. Enter the following command to run a configuration script that will prepare the right installation for your specific system:

./configure

Next, enter the following command to compile Node:

make

Node normally takes a little while to compile, so be patient and expect to see a lot of text scroll by. The text is information related to the compiling process and can be ignored.

A Cygwin quirk

If you’re running Cygwin on Windows 7 or Vista, you may run into errors during this step. These are due to an issue with Cygwin rather than an issue with Node. To address them, exit the Cygwin shell, and then run the ash.exe command-line application (located in the Cygwin directory; usually c:\cygwin\bin\ash.exe). On the ash command line, enter /bin /rebaseall -v. When this completes, restart your computer. This should fix your Cygwin issues.

At this point, you’re almost done. Once text stops scrolling and you again see the command prompt, you can enter the final command in the installation process:

sudo make install

When that’s finished, enter the following command to run Node and have it display its version number, verifying that it has been successfully installed:

node -v

You should now have Node on your machine!

A.5. Using the Node Package Manager

With Node installed, you’ll be able to use built-in modules that provide you with APIs to perform networking tasks, interact with the filesystem, and do other things commonly needed in applications. Node’s built-in modules are referred to collectively as the Node core. While Node’s core encompasses a lot of useful functionality, you’ll likely want to use community-created functionality as well. Figure A.3 shows, conceptually, the relationship between the Node core and add-on modules.

Figure A.3. The Node stack is composed of globally available functionality, core modules, and community-created modules.

Depending on what language you’ve been working in, you may or may not be familiar with the idea of community repositories of add-on functionality. These repositories are akin to libraries of useful application building blocks that can help you do things that the language itself doesn’t easily allow out of the box. These repositories are usually modular: rather than fetching the entire library all at once, you can usually fetch just the add-ons you need.

The Node community has its own tool for managing community add-ons: the Node Package Manager (npm). In this section, you’ll learn how to use npm to find community add-ons, view add-on documentation, and explore the source code of add-ons.

npm is missing on my system

If you’ve installed Node, then npm is likely already installed. You can test it by running npm on the command line and seeing if the command is found. If not, you can install npm by doing the following:

cd /tmp

git clone git://github.com/isaacs/npm.git

cd npm

sudo make install

Once you’ve installed npm, enter the following on a command line to verify that npm is working (by asking it to output its version number):

npm -v

If npm has installed correctly, you should see a number similar to the following:

1.0.3

If you run into problems installing npm, the best thing to do is to visit the npm project on GitHub (http://github.com/isaacs/npm), where the latest installation instructions can be found.

A.5.1. Searching for packages

The npm command-line tool provides convenient access to community add-ons. These add-on modules are referred to as packages and are stored in an online repository. For users of PHP, Ruby, and Perl, npm is analogous to PEAR, Gem, and CPAN, respectively.

The npm tool is extremely convenient. With npm you can download and install a package using a single command. You can also easily search for packages, view package documentation, explore a package’s source code, and publish your own packages so they can be shared with the Node community.

You can use npm’s search command to find packages available in its repository. For example, if you wanted to search for an XML generator, you could simply enter this command:

npm search xml generator

The first time npm does a search, there’s a long pause as it downloads repository information. Subsequent searches, however, are quick.

As an alternative to command-line searching, the npm project also maintains a web search interface to the repository: http://search.npmjs.org/. This website, shown in figure A.4, also provides statistics on how many packages exist, which packages are the most depended on by others, and which packages have recently been updated.

Figure A.4. The npm search website provides useful statistics on module popularity.

The npm web search interface also lets you browse individual packages, showing useful data such as the package dependencies and the online location of a project’s version control repository.

A.5.2. Installing packages

Once you’ve found packages you’d like to install, there are two main ways of doing so using npm: locally and globally.

Locally installing a package puts the downloaded module into a folder called node_modules in the current working directory. If this folder doesn’t exist, npm will create it.

Here’s an example of installing the express package locally:

npm install express

Globally installing a package puts the downloaded module into the /usr/local directory on non-Windows operating systems, a directory traditionally used by Unix to store user-installed applications. In Windows, the Appdata\Roaming\npm subdirectory of your user directory is where globally installed npm modules are put.

Here’s an example of installing the express package globally:

npm install -g express

If you don’t have sufficient file permissions when installing globally, you may have to prefix your command with sudo. For example,

sudo npm install -g express

After you’ve installed a package, the next step is figuring out how it works. Luckily, npm makes this easy.

A.5.3. Exploring documentation and package code

The npm tool offers a convenient way to view a package author’s online documentation, when available. The docs npm command will open a web browser with a specified package’s documentation. Here’s an example of viewing documentation for the express package:

npm docs express

You can view package documentation even if the package isn’t installed.

If a package’s documentation is incomplete or unclear, it’s often handy to be able to check out the package’s source files. The npm tool provides an easy way to spawn a subshell with the working directory set to the top-level directory of a package’s source files. Here’s an example of exploring the source files of a locally installed express package:

npm explore express

To explore the source of a globally installed package, simply add the -g command-line option after npm. For example:

npm -g explore express

Exploring a package is also a great way to learn. Reading Node source code often introduces you to unfamiliar programming techniques and ways of organizing code.