node.js and npm

Intro to Node.js and npm

Lessons

Package Management using npm

In this lesson, we will learn how to use the package manager npm, a node.js command line client, to setup a custom front-end web development environment and automated build process.

A package manager (or package management system) is a collection of tools that automates the process of installing, upgrading, configuring, and removing software in a consistent manner.
– Wikipedia

npm is a package manager for the JavaScript programming language. It is the default package manager for the JavaScript runtime environment Node.js. It consists of a command line client, also called npm, and an online database of public and paid-for private packages, called the npm registry. The registry is accessed via the client, and the available packages can be browsed and searched via the npm website. The package manager and the registry are managed by npm, Inc.
– Wikipedia

Node.js is an open-source, cross-platform JavaScript run-time environment for executing JavaScript code server-side. Historically, JavaScript was used primarily for client-side scripting, in which scripts written in JavaScript are embedded in a webpage’s HTML, to be run client-side by a JavaScript engine in the user’s web browser. Node.js enables JavaScript to be used for server-side scripting, and runs scripts server-side to produce dynamic web page content before the page is sent to the user’s web browser. Consequently, Node.js has become one of the foundational elements of the “JavaScript everywhere” paradigm, allowing web application development to unify around a single programming language, rather than rely on a different language for writing server side scripts.
– Wikipedia

Why use a package manager like npm?

As front-end web development environments and build tools become more and more complex, the amount of time spent setting up new projects can be exhaustive. To avoid wasting time via repetition, package managers help to simplify the process with one simple command: npm install.

$ npm install

Package managers like npm can save front-end developers a lot of time, especially when starting new projects from scratch (e.g. to avoid setting up everything manually), when working with complex projects with multiple dependencies (e.g. to avoid installing each dependency with the latest version of each), and when working on large projects with multiple developers (to ensure a consistency across all computers).

Outcomes

  1. Learn how to install an existing npm-based web project
  2. Learn how to setup a custom npm-based web project from scratch

Steps

  1. Install Node.js and npm
  2. Install an existing npm project (Sitebase 3)
  3. Setup a custom npm project from scratch (my-npm-project)

Step 1

Install Node.js and npm

Make sure that you have node.js installed.

$ node -v
$ npm -v

If installed, you should see the version number for each. If not, you’ll need to download Node.js from https://nodejs.org/en/ and follow their installation instructions.

Step 2

Install an existing npm project: Sitebase 3

Inside of your target parent directory (the folder where you will be placing your new project folder), copy the source project files for Sitebase 3.0 on Github. If you already have git installed and/or already have a github account, from inside of your target parent directory, you can simply clone the repo:

$ git clone https://github.com/kccnma/sitebase3-npmgulp

If you do not have git installed, you can download the zip file (https://github.com/kccnma/sitebase3-npmgulp/archive/master.zip) then manually unzip it into your target parent directory.

Once copied/cloned, your local environment should look like this:

targetparentdirectory/
   └── sitebase3-npmgulp/
         ├── dist/
         ├── src/
         ├── .gitignore
         ├── README.md
         ├── gulpfile.js
         ├── package.json

Take a look inside of package.json and you’ll notice two sections toward the bottom: dependencies and devDependencies. These are the list of dependencies that this existing project is already using. In this case, this project is using gulp as a task manager to watch for changes, compile source files (e.g. SASS via a gulp plugin called gulp-sass), sync browsers (via browser-sync), compress all images (via gulp-imagemin), and then compile and copy all final files into the /dist/ folder.

Testing

If you try to run gulp right away, it will not work. You’ll get an error (e.g. "Local gulp not found"). The key step (whenever you are setting up a new project via npm) is to run npm install from inside of your project folder first. Note: you only need to do this once.

$ cd sitebase3-npmgulp
$ npm install

You’ll notice a progress bar as npm installs all of the project dependencies. Afterward, you’ll notice a new folder was created entitled “node_modules” that contains all of the dependencies. Note: this “node_modules” folder is quite large, so if you are using git, be sure to add it to your .gitignore file (which is already included as part of Sitebase 3).

To test it out, run gulp and see if it works. It should spin up a web server, launch the project in a browser, and watch your files for changes.

$ gulp

Congratulations – you just setup your first npm-based web project!

Step 3 (Optional/Advanced)

Advanced: Setup a custom npm project from scratch (my-npm-project)

Let’s say you do not want to start from an existing project or base, and would prefer to setup a completely new npm-based project from scratch. The steps are simple:

npm init

First, wherever you are working (e.g. your target parent folder), create a new primary “projectname” folder to be the project root directory. Then, run the npm init command from inside your target parent directory.

$ npm init

The npm init command will create a package.json file that will store information about the project, such as the dependencies used in the project (e.g. Gulp, Sass, etc.) and it will also create a new “node_modules” folder that will include all dependencies. In order to create the package.json file with accurate information, it will prompt you "Is this ok? (yes)? Type yes.

If you look inside of your project folder, you should see both the new package.json file and the new node_modules folder.

Add Dependencies

Once you have your package.json file all set up and ready, whenever you need to add a new dependency to your project, you’ll need to 1) manually install each dependency and 2) save it to your list of dependencies inside of your project’s package.json file. This two-part process is actually quite simple and done in one step via the following command:

$ npm install dependencyname --save-dev (replacing dependencyname with the name of your dependency)

Be sure to include the "--save-dev" part, or else the dependency will not be added to your list of dependencies inside of your project’s package.json file. As an example, let’s install gulp.

$ npm install gulp --save-dev

If you look inside of your package.json file, you should see “gulp” along with the version number inside of the “devDependencies” area.

Since this lesson is about npm (not gulp), we are not going to create a complex gulpfile.js. However, we can setup a quick one to test that our custom environment is working OK.

First, we’ll need to create a new file named “gulpfile.js” that will store all of your gulp tasks. I suggest using your favorite text editor (IDE) for this step. Inside of your gulpfile.js, we’ll need to add a task for testing purposes. Whenever you add a new task using gulp, such as adding a new dependency, it is a 2-step process:

1) First, you need to add a “require” statement that will tell Node to look into the node_modules folder for the new package (in this case it is a package named gulp). To do this, you need to create a new variable named gulp and assign the plugin contents to it:

var gulp = require('gulp');

2) Next, you need to define the task. The following is the syntax for a typical gulp task:

gulp.task('task-name', function() {
    // Statements go here
});

In this case, we are going to do a simple “Hello” console log statement to a task named hello.

gulp.task('hello', function() {
    console.log('Hello');
});

After you saved your gulpfile from your text editor, switch to your command line interface and test it out via the following command:

$ gulp hello

Setting up a bespoke gulpfile.js can be daunting, so I suggest checking out a boilerplate, such as this one.

Closing thoughts:

Project managers can speed up the setup and installation of project dependencies, build tools, and processes. Once you have npm installed on your machine, you can quickly and easily take advantage of existing npm-based projects that use npm install for project setup and the many npm packages and dependencies that it supports.

Resources: