Taxonomy Icon

Node.js

In this tutorial, I give you a quick overview of Node.js and show you how to install the software you need to complete the Node.js Learning Path.

First, you need to install the Node.js runtime itself, along with Node’s package manager, npm. Then you need to install an editor in which to write your source code as you complete the units of the LP. You’re welcome to use any editor you like, but I recommend you use VSCode (for reasons I’ll outline later in this unit). It’s free, open source, has a bazillion plugins, and it’s built on Node.

Prerequisites

You need to install the git client for your platform. Links to instructions for Windows, MacOS, and Linux are below.

Click on this link, scroll down to the section that matches your platform, and follow the instructions.

Install Node.js and npm

There are several ways you can install Node.js. The easiest approach is to download the package for your platform directly from the Nodejs.org website’s Downloads page and run the installation program. This is definitely the way to go if you’re a Windows user, but this approach works for MacOS and Linux as well.

If you’re a Mac user, a better approach is to use Homebrew. Homebrew bills itself as the “missing package manager for MacOS.” You can use it to install and manage hundreds of different packages for MacOS.

The best way to install Node.js and npm is through Node.js Version Manager, or nvm. With nvm, you can install multiple versions of both the Node.js runtime and npm, and they can all coexist, though you can only specify one active version of either at a time. What I mean is, you don’t have to uninstall one version of Node.js or npm to install another, just tell nvm which one you want to use. It’s great for compatibility testing and managing your Node.js environment in general.

I’ve summarized the pros and cons of each approach in the table below:

Installation type Pros Cons
Straight download from nodejs.org Simple, Most platforms supported Manual checksum validation
Homebrew Simple, Automatic Checksum validation, Can swap between multiple versions** MacOS only
nvm Simple, Automatic checksum validation, Can easily swap between multiple versions MacOS and Linux only (community contribs for other platforms are available)

** by jumping through a few hoops, as I’ll show you later in the tutorial.

Homebrew and nvm offer automatic checksum validation (which is nice), but have limited officially supported platforms. I describe each approach in detail in the sections that follow, so you can choose the approach that is right for you.

Which release of Node.js to use

On the Downloads page, you have to choose between the LTS (Long-Term Support) or Current release. But what does this mean?

The frequent release cycle of open source software is a double-edged sword. On the one hand, new features are released and bugs are addressed in a timely manner. But, on the other hand, you have to deal with upgrade issues resulting from those frequent release cycles. It can be very destabilizing for business applications to have to upgrade the underlying runtime multiple times per year.

To address this issue, the Node.js release team designates even-numbered major releases as LTS releases. The LTS releases are supported for up to three years from the date of its original release, during which time the release goes from Current (~6 months) to Active LTS (18 months, minor revisions only) to Maintenance LTS (12 months, patch releases only). But this means you can be sure that an LTS release will be stable for a considerable period of time.

If you want to know more about the Node.js release process, check out the Release page. This page includes lots of great information including the release schedule, the release mandate, and the methodology for LTS releases (along with what goes in them).

For the LP, I use version 10, which (at the time of this writing) is the current LTS release. You probably want to do the same to ensure you can follow along.

Checksums

It’s always a good idea to do a quick checksum check on any open source downloads you do, including any or all of the ones in this unit. Not convinced? Check out this post at ServerFault (one of the StackExchange sites).

I use a Mac, so I’ll show you how to do checksum validation on a download for MacOS. There are plenty of resources on the web for how to perform checksum validation if you’re running a different platform.

First, you need the checksum from the website where you downloaded the file. It usually looks something like this:

Figure 1

This example is from nodejs.org for the file node-v10.4.0.pkg. Copy the checksum (the long string of characters to the left of the file name above) and paste that into an editor (I keep TextEdit in my dock just for this purpose).

Now open a Terminal window and navigate to your Downloads directory (or wherever you downloaded the file) and run the shasum command on the downloaded file:

Figure 2

Paste the string into the editor just below the checksum from the website and compare them:

Figure 3

Get in the habit of doing this checksum validation for every file you download. To save space, I won’t include these details for the downloads in the rest of this tutorial, but trust me, I did a checksum verification on each and every file.

Now, onto the installations!

Good: Download installation package from nodejs.org website

Go to the Downloads page, and click on the installer that matches your platform.

As I said in the previous section, I use version 10 for the Learning Path, and this is reflected in all instructions in this section, including the video. I suggest you use version 10.4.0 (or whatever is the latest 10.x.y release at the time), which will almost certainly be the LTS release when you read this (or very close).

Once the installer is downloaded to your computer, and you have verified the checksum matches, launch the installer. On my Mac, for example, I double click on the Package installer program (called node-v10.4.0.pkg) to run the package installer. I show you how to do this in the video. If you’re running Windows, double click the installer and follow the steps in the installation wizard.

For Linux, unpack the tarball to a standard location such as /usr/local/lib/nodejs, making sure that the path to the Node.js bin directory matches your PATH environment variable. See this link from the Node.js GitHub Wiki for more detailed instructions.

Now skip to Verify the Installation section to confirm that Node.js and npm were installed correctly.

Going forward, when you want to upgrade your version of Node.js, download the new installer and it will replace the current version.

Using this method of installation, you may have only one version of Node.js and npm installed at a time. If you want to have multiple versions installed and switch back and forth among them (for compatibility testing, let’s say), I recommend you use nvm (See Best: Use nvm for details).

Better: Use Homebrew (MacOS only)

Homebrew is a better way to manage various packages on your Mac. Whenever I need to install a familiar Linux package, I check to see if it is available as a Homebrew “formula” first before trying to install the package another way (with rare exceptions like using nvm for managing Node.js, which I’ll show you in the next section).

To learn more about Homebrew and how to install it, check out the Installation page.

To install the current version of Node.js and npm via Homebrew, open a Terminal window on your Mac and enter this command:

brew install node

However, I highly recommend you install specific major versions of Node.js as a matter of practice, since it forces you to be aware of exactly what version you’re installing. If the specific major version you install happens to be the current version, then Homebrew will link it for you automatically (meaning, it will create symbolic links to node and npm in your PATH to the current version in the Homebrew Cellar). Plus, you can switch between installed versions by unlinking one and linking another using the brew unlink and brew link commands (though you should use this with caution, as I’ll show you later in this section).

To install the latest Node.js version 10, enter the brew install node@10 command. You’ll see output like this:

$ brew install node@10
Updating Homebrew...
==> Auto-updated Homebrew!
Updated 1 tap (homebrew/core).
No changes to formulae.
==> Downloading https://homebrew.bintray.com/bottles/node-10.4.0.high_sierra.bottle.tar.gz
######################################################################## 100.0%
==> Pouring node-10.4.0.high_sierra.bottle.tar.gz
==> Caveats
Bash completion has been installed to:
  /usr/local/etc/bash_completion.d
==> Summary
p
:  /usr/local/Cellar/node/10.4.0: 6,793 files, 59.6MB
$

Now skip to the Verify the Installation section to confirm that Node.js and npm were installed correctly.

Note: homebrew always installs the current version of Node.js when you use the command as I’ve shown it above. If you want to install a specific major version of Node.js, you specify the major version number like this:

brew install node@8

You’ll see output like this:

$ brew install node@8
==> Downloading https://homebrew.bintray.com/bottles/node@8-8.11.2.high_sierra.bottle.tar.gz
######################################################################## 100.0%
==> Pouring node@8-8.11.2.high_sierra.bottle.tar.gz
==> Caveats
This formula is keg-only, which means it was not symlinked into /usr/local,
because this is an alternate version of another formula.
If you need to have this software first in your PATH run:
  echo 'export PATH="/usr/local/opt/node@8/bin:$PATH"' >> ~/.bash_profile
For compilers to find this software you may need to set:
    LDFLAGS:  -L/usr/local/opt/node@8/lib
    CPPFLAGS: -I/usr/local/opt/node@8/include
==> Summary
p
:  /usr/local/Cellar/node@8/8.11.2: 4,430 files, 47MB

This installs the latest version of Node.js 8, which means the latest minor.patch release only. Note: if the version you install is not the current version of Node.js (even if it is the active LTS), it will be a “keg-only” install. See “What does keg-only mean?” in the Homebrew FAQ for more info.

Going forward, to upgrade Node.js use:

brew upgrade node

If there is an upgrade available, it is automatically applied for you.

Switching between multiple versions

Homebrew allows you to have multiple major versions of Node.js and npm installed at a time, but only one may be active. If you want to switch between them, you must “unlink” the actively linked version, and “link” the one you want to use.

On my Mac this means I have to jump through a few hoops (involving --force and --overwrite) to switch from version 10 to version 8, and more than once I’ve accidentally left my system in a weird state (as in, -bash: /usr/local/bin/npm: No such file or directory). For example, here’s what I have to go through to switch from Node.js 10 to Node.js 8 and back to Node.js 10:

Ix:~ sperry$ brew unlink node
Unlinking /usr/local/Cellar/node/10.4.0... 7 symlinks removed
Ix:~ sperry$ brew link --force --overwrite node@8
Linking /usr/local/Cellar/node@8/8.11.2... 4287 symlinks created
If you need to have this software first in your PATH instead consider running:
  echo 'export PATH="/usr/local/opt/node@8/bin:$PATH"' >> ~/.bash_profile
Ix:~ sperry$ node -v
v8.11.2
Ix:~ sperry$ npm -v
5.6.0
Ix:~ sperry$ brew unlink node@8
Unlinking /usr/local/Cellar/node@8/8.11.2... 4287 symlinks removed
Ix:~ sperry$ brew link node
Linking /usr/local/Cellar/node/10.4.0... 7 symlinks created
Ix:~ sperry$ node -v
v10.4.0
Ix:~ sperry$ npm -v
-bash: /usr/local/bin/npm: No such file or directory
Ix:~ sperry$ brew reinstall node
==> Reinstalling node
==> Downloading https://homebrew.bintray.com/bottles/node-10.4.0.high_sierra.bottle.tar.gz
Already downloaded: /Users/sperry/Library/Caches/Homebrew/node-10.4.0.high_sierra.bottle.tar.gz
==> Pouring node-10.4.0.high_sierra.bottle.tar.gz
==> Caveats
Bash completion has been installed to:
  /usr/local/etc/bash_completion.d
==> Summary
p
:  /usr/local/Cellar/node/10.4.0: 6,793 files, 59.6MB
Ix:~ sperry$ npm -v
6.1.0
Ix:~ sperry$

Yikes, what a pain! However, as you can see, I got it to work. But I ended up having to reinstall Node.js 10 because the unlink from Node.js 8 caused something to go wrong. Maybe I did something incorrectly. Maybe Homebrew just doesn’t like me. Maybe there was a full moon last night. Who knows?

If you really need to switch painlessly between versions of Node.js and npm, I highly recommend you use nvm. Also, if you want to have multiple major.minor.patch versions installed and switch back and forth among them (for compatibility testing, let’s say), you must use nvm, since Homebrew only supports installing the latest major.minor.patch release.

What about checksum validation? Homebrew does checksum validation for you automatically, which is one more reason to use it versus a straight package install.

Best: Use nvm (MacOS and Linux only)

Sorry, Windows users. NVM is officially only supported on MacOS and Linux, but there are two alternatives (neither of which is officially supported by the NVM team, though I got these links from the NVM GitHub site, so wink wink):

Other unsupported platforms are listed as well under Important Notes.

Installing nvm is a snap. Go to the creationix GitHub repo, and scroll down to the Installation section (or click this link. Copy the install command and paste it into a Terminal window or command prompt:

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash

It takes just a few seconds (less than 10 on my Mac) to download and install.

The install script makes changes to your .bash_profile (MacOS) or .profile (Linux), so when the script finishes, you’ll need to rerun your profile script using your favorite method for doing so. I’m lazy, so I’ll just stop the Terminal window and open a new one.

Verify that nvm installed correctly by running the nvm --version command. You should see output like this:

$ nvm --version
0.33.11

To install Node.js and npm run the nvm install --lts command which tells nvm to install the LTS version (which at the time of this writing is Node.js 8.11.2 and npm 5.6.0):

$ nvm install --lts
Installing latest LTS version.
Downloading and installing node v8.11.2...
Downloading https://nodejs.org/dist/v8.11.2/node-v8.11.2-darwin-x64.tar.gz...
######################################################################## 100.0%
Computing checksum with shasum -a 256
Checksums matched!
Now using node v8.11.2 (npm v5.6.0)

Now verify the installation using the instructions in the next section.

Switching between multiple versions with nvm

You can install multiple versions of Node.js and npm installed (including any major.minor.patch combination that has been released) and switch back and forth between them. This is great for compatibility testing, for example. Suppose you want to install Node.js 10 (which at the time of this writing is 10.4.0):

$ nvm install 10
Downloading and installing node v10.4.0...
Downloading https://nodejs.org/dist/v10.4.0/node-v10.4.0-darwin-x64.tar.gz...
######################################################################## 100.0%
Computing checksum with shasum -a 256
Checksums matched!
Now using node v10.4.0 (npm v6.1.0)
$ node -v
v10.4.0
Ix:~ sperry$ npm -v
6.1.0

Then switch back to Node.js 8 (I’ll assume you’ve been following along with this tutorial, and the version in use is 10):

Ix:~ sperry$ nvm use 8
Now using node v8.11.2 (npm v5.6.0)
Ix:~ sperry$ node -v
v8.11.2
Ix:~ sperry$ npm -v
5.6.0

Check it out! I can swap out the Node runtime on the PATH with a simple command. Pretty cool.

Notice that the version of npm is also upgraded to match the version of Node you downloaded. Unless you specify otherwise, Node.js and npm are sort of a package deal (and that’s usually a good thing).

To see all the options available, just type nvm and this help screen appears:

Usage:
  nvm --help                                Show this message
  nvm --version                             Print out the installed version of nvm
  nvm install [-s] <version>                Download and install a <version>, [-s] from source. Uses .nvmrc if available
    --reinstall-packages-from=<version>     When installing, reinstall packages installed in <node|iojs|node version number>
    --lts                                   When installing, only select from LTS (long-term support) versions
    --lts=<LTS name>                        When installing, only select from versions for a specific LTS line
    --skip-default-packages                 When installing, skip the default-packages file if it exists
    --latest-npm                            After installing, attempt to upgrade to the latest working npm on the given node version
  nvm uninstall <version>                   Uninstall a version
  nvm uninstall --lts                       Uninstall using automatic LTS (long-term support) alias `lts/*`, if available.
  nvm uninstall --lts=<LTS name>            Uninstall using automatic alias for provided LTS line, if available.
  nvm use [--silent] <version>              Modify PATH to use <version>. Uses .nvmrc if available
    --lts                                   Uses automatic LTS (long-term support) alias `lts/*`, if available.
    --lts=<LTS name>                        Uses automatic alias for provided LTS line, if available.
  nvm exec [--silent] <version> [<command>] Run <command> on <version>. Uses .nvmrc if available
    --lts                                   Uses automatic LTS (long-term support) alias `lts/*`, if available.
    --lts=<LTS name>                        Uses automatic alias for provided LTS line, if available.
  nvm run [--silent] <version> [<args>]     Run `node` on <version> with <args> as arguments. Uses .nvmrc if available
    --lts                                   Uses automatic LTS (long-term support) alias `lts/*`, if available.
    --lts=<LTS name>                        Uses automatic alias for provided LTS line, if available.
  nvm current                               Display currently activated version
  nvm ls                                    List installed versions
  nvm ls <version>                          List versions matching a given <version>
  nvm ls-remote                             List remote versions available for install
    --lts                                   When listing, only show LTS (long-term support) versions
  nvm ls-remote <version>                   List remote versions available for install, matching a given <version>
    --lts                                   When listing, only show LTS (long-term support) versions
    --lts=<LTS name>                        When listing, only show versions for a specific LTS line
  nvm version <version>                     Resolve the given description to a single local version
  nvm version-remote <version>              Resolve the given description to a single remote version
    --lts                                   When listing, only select from LTS (long-term support) versions
    --lts=<LTS name>                        When listing, only select from versions for a specific LTS line
  nvm deactivate                            Undo effects of `nvm` on current shell
  nvm alias [<pattern>]                     Show all aliases beginning with <pattern>
  nvm alias <name> <version>                Set an alias named <name> pointing to <version>
  nvm unalias <name>                        Deletes the alias named <name>
  nvm install-latest-npm                    Attempt to upgrade to the latest working `npm` on the current node version
  nvm reinstall-packages <version>          Reinstall global `npm` packages contained in <version> to current version
  nvm unload                                Unload `nvm` from shell
  nvm which [current | <version>]           Display path to installed node version. Uses .nvmrc if available
  nvm cache dir                             Display path to the cache directory for nvm
  nvm cache clear                           Empty cache directory for nvm
Example:
  nvm install 8.0.0                     Install a specific version number
  nvm use 8.0                           Use the latest available 8.0.x release
  nvm run 6.10.3 app.js                 Run app.js using node 6.10.3
  nvm exec 4.8.3 node app.js            Run `node app.js` with the PATH pointing to node 4.8.3
  nvm alias default 8.1.0               Set default node version on a shell
  nvm alias default node                Always default to the latest available node version on a shell
Note:
  to remove, delete, or uninstall nvm - just remove the `$NVM_DIR` folder (usually `~/.nvm`)

You can also check out the NVM documentation.

Verify the installation

Once Node.js and npm are installed, verify that they are installed correctly:

node -v
npm -v

You should see output like this:

$ node -v
v10.4.0
$ npm -v
6.1.0

Make sure that /usr/local/bin is on your PATH environment variable or you may see output like this:

$ node
-bash: node: command not found

Get the source code from GitHub

I’ve provided source code for every example in the Learning Path, which is available in GitHub.

Open a terminal window, navigate to a directory where you want the code to land, and enter the git clone command:

git clone https://github.com/jstevenperry/IBM-Code

Then navigate to the Node.js/Course directory. There you will find all of the examples I show throughout the course.

Install VSCode

To follow along with all the tutorials in the Learning Path, you need an editor. I have used VSCode for a couple of years now and really like it. It’s free, open source, and has an active user community with lots of extensions, which means you’re likely to find lots of different extensions for your favorite language, platform, or file format. Plus, VSCode is built on the Electron framework which uses Node.js under the hood.

Of course, you’re free to use whatever editor you like. For the tutorials in this series, I use VSCode, so all the screenshots and video captures you see are of VSCode.

To install VSCode, go to code.visualstudio.com. Your browser should auto-detect your platform and prefill the dropdown with the matching download, or use the dropdown to select any other download you like. However, I recommend you visit the downloads page where you can also obtain the SHA256 checksum for your download. To see the checksum, click the link at the bottom of the page titled “See SHA-256 Hashes”, which will expand showing a list of hashes for each file.

The file that is downloaded will vary by platform. For MacOS, the downloaded file is a ZIP archive containing a MacOS App file. Copy the file to your applications folder, so you can easily locate it later if you like.

If you’re running on Windows, the file is an installer. Instructions for installing it are here.

If you’re running Linux, you can find setup instructions here.

Once you have VSCode installed, go ahead and launch it. You should definitely checkout the Marketplace, which has TONS of plugins.

To install a plugin, click on the Marketplace icon, search for plugin you want, and click Install. Figure 4 shows some of the extensions I have installed:

Figure 4

Running Node.js in VSCode

VSCode plugs into the Node.js runtime, so you can run your code from within VSCode. Follow these steps:

  1. Navigate to the directory where you cloned the code.
  2. In VSCode, choose File > Open and select the IBM-Code/Node.js/Course subdirectory within that location, and click the Open button.
  3. Click on the File tab, expand the Unit-2 folder and click on example1.js to open it in the editor.
  4. Click the Debug tab.
  5. Click on the Run button.

The JavaScript file will run in the debug window. You should see something like Figure 5 when it is finished.

Figure 5 Figure 5 – the VSCode debug window.

Now you can run all of the examples in this course either from the command line, or from within VSCode.

Conclusion

In this tutorial, I showed you three different ways you can install Node.js and npm, and the advantages and disadvantages of each. Then I showed you how to install VSCode.

In the next part of the series, I introduce you to basic Node.js concepts, and you write some JavaScript code!

Video

In the video, I show you how to install Node.js and npm three different ways, and how to install VSCode on the Mac.