NPM

Intro

This is the second in a series of tutorials on Node.js.

In the first tutorial we created a project folder called nodejs-tutorial. For each tutorial we are creating a new folder.

If you are following along, open the project in your text editor and create a new folder named 2-npm.
Open your Terminal application and go into nodejs-tutorial/2-npm.

The code for the whole series is available on GitHub at github.com/LearnByCheating/nodejs-tutorial
Read it, watch it, do it, review it:

There are both a written and accompanying video version of this tutorial. There are timestamps under the headings that align with the video version of the topic.

Read it: For each topic heading, first read the topic.
Watch it: Then watch the associated section of the video.
Do it: Then follow the instructions to replicate the steps on your computer.

The Node.js CheatSheet has a major category that aligns with this tutorial.

Review it: When you are done with the whole tutorial, open the CheatSheet and review the NPM category from this tutorial. Make sure you understand everything, and can refer back to the CheatSheet when you are working on your own projects in the future.

What is npm?

[0:00 Video timestamp]

Npm (Node Package Manager) is a program that allows you to download and integrate third party packages into your Node project.
Npm is automatically installed when you install or upgrade Node.js.

To see the list of npm packages available, go to npm's package repository: Npmjs.com

Npm commands are run from the command line.

Npm help / Online manual

[0:21 Video timestamp]

To get a list of available npm commands run npm help
To get information on a specific command run npm help then the command name: npm help command
Example: get help on the npm init command: npm help init

Npm help uses the Unix Less paging program to display help topics.
Navigate: To navigate through the help page use the following keyboard commands:

downArrow | return go down one line, upArrow go up one line.
g go to the start of the help page, G go to the end of the help page.

d go down half a screen, u go up half a screen.
f | space go forward (down) one full screen, b go backward (up) one full screen.

Search: To search for a term or phrase in the help page use the search command:

/search-term Enter a forward slash, then the search term.
n Go to the next instance of the found search items. N Go to the previous instance.

Quit: q Quits the Less paging program taking you back to the Node prompt.

Package.json

[0:40 Video timestamp]

Node uses a file called package.json to:

Manage third party Node packages,
Add meta information about your app,
Add scripts that you can run from the command line.

Npm init command

[0:51 Video timestamp]

You can create a package.json file by hand, or generate one with the command npm init. We'll do the latter.

Open the Terminal and go to the nodejs-tutorial/2-npm folder.
Then create a folder called myproj to hold your project. You can use the Unix command:
mkdir myproj
Then change directories into the project folder:
cd myproj

Now run the npm init command We'll add the --yes | -y option to use the defaults.
npm init -y

This generates the file in the current directory.
It looks like the below. It uses the directory name as the name of the project.

package.json

{
  "name": "myproj",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

You can edit this file as needed:
Let's change the main and script properties:

"main": "app.js",
"scripts": {
  "start": "node app.js",
  "test": "jest --coverage"
},

package.json "main" property

[1:12 Video timestamp]

The "main" property sets the name of the file that runs your app.

The default is index.js, let's change it to app.js

package.json scripts

[1:22 Video timestamp]

Package.json scripts execute command line commands. The property name calls the script value.

We added two scripts:

"main": "app.js",
"scripts": {
  "start": "node app.js",
  "test": "jest --coverage"
},

Start Script

[1:32 Video timestamp]

Now you can start the app in one of three ways.

node app - First is the regular way. Call the node command and pass in the app file as the argument.
npm . - Second, since we set the main property to app.js we can simply call node on the directory and it will open the app.js file. Dot means the current directory.
npm start - The third way is to call our script.

You call a script with npm run then the script name: node run start.
But Node allows a shortcut on the start command since it is so common. Just enter npm start without the run command.
Running the script executes the command in the script value: "node app.js"

We also have a script to run a test package called jest which we haven't installed yet.
We could run it either of these ways:

jest --coverage - Enter the jest command directly.
npm run test or just npm test - Or call the npm script to run it. Like start, test is a very common script, and does not require the run command.

Install npm packages

[2:15 Video timestamp]

Local Packages

Now we will cover installing npm packages into your project.
If you already know what packages you need, run npm install, then the package names:
npm install packageName
You can use the i alias for install
npm i packageName

In the Terminal, make sure you are in the nodejs-tutorial/2-npm/myproj directory.
Then install two packages. Express is a popular web framework package and ejs is its templating engine.
npm install express ejs

This will do three things:

node_modules: Node will download the latest version of these packages, and all their dependencies from the npm package repository, and install them in the node_modules directory in your project. If node_modules does not exist it will automatically be created.
package.json dependencies: The package name and version will be added to the package.json file under dependencies.
package-lock.json: The package name and version and all if it's dependencies will be added to the package-lock.json file. If the file doesn't exist, it will be created. Do not edit this file.

Packages often have their own dependencies, so when you install them, the dependencies will automatically be installed as well. Express is fairly complicated package and has a large number of dependencies.

If one or both of the packages are already installed, npm will update them to the latest version depending on how your packages are listed in package.json (covered below). The old version will be deleted. If they are already on the latest version then nothing will happen.

Development Dependencies

[2:35 Video timestamp]

If the package you are installing is only needed for development and not in production, you can install it as a development dependency. That way it will won't be installed on your production server where it's not needed.
The command to install a development dependency is:
npm install packageName --save-dev
You can use the i alias and short option:
npm i packageName -D

Let's install the jest testing framework as a development dependency
npm i jest -D

Using local packages in your project

[3:00 Video timestamp]

Locally installed packages can be used inside your app files by importing the module, then accessing its properties and methods in your files.
This is covered elsewhere but the CommonJS format for importing a package is:

Import package to a file: const package = require('packageName');
Use it in the same file: package.method();

Global Packages

[3:32 Video timestamp]

There are some packages that are meant to be run from the command line.

[3:37 Video timestamp]
Nodemon is a good example of this. It allows you to run your app in development with hot reloading.
Then instead of running your app with:
node myproj
you would run it with:
nodemon myproj
Then very time you save a JavaScript or JSON file in your app, nodemon will relaunch the app automatically.

[3:49 Video timestamp]
Packages run from the command line can be installed globally, making them available to all your apps.
Note, the accompanying video uses the option --location=global.
Instead use the shorter version --global or just -g.

To install a package globally run:
npm install package_name --global
Or using the i alias and short option:
npm i package_name -g

Let's install nodemon globally:
npm i nodemon -g
If you already installed it in the previous tutorial it will just try to update it.
If you get a permissions error, try running it as the superuser with the sudo command
sudo npm i nodemon -g

Why would you get a permissions error?

On a Mac, global npm packages are installed in /usr/local/lib/node_modules/ with an alias in the /usr/local/bin folder which is in the default path.
You can confirm the location of the executable file by entering which nodemon
Because both of these are system folders and not inside your user's directory, you won't have access to those directories by default. If this is your own computer, you are probably also a superuser. Sudo lets you run the command as a superuser.

Npx command

[4:16 Video timestamp]

The npx command lets you run a package without installing it.
It loads a temporary copy, runs it, then discards it.

Express-generator is a package you run from the command line that generates a basic web server using Express and a few other npm packages.
While you could install express-generator as a global package, it is a good candidate for using npx instead.
Unlike nodemon, you probably won't use it often so there is no need to have a locally installed copy.
And you won't have to worry about keeping it updated, since npx will use the latest version.

Back out of the myproj directory into the 2-npm folder:
cd ..

Then enter the below npx command to run the express-generator package without having to install it first.
npx express-generator --view=ejs my-express-site
Express-generator with the ejs view option will generate a basic web app, create the folder with the name provided (my-express-site), and place the app inside it.

List Installed Packages

[4:49 Video timestamp]

To list locally installed packages enter:
npm list

To list globally installed packages enter:
npm list --global or npm list -g

Semantic Versioning

[5:09 Video timestamp]

Npm uses semantic versioning in the format of 3 numbers separated by periods: Major.Minor.Patch

Major updates generally include major new features, and may include breaking changes. Deprecated features are features that are scheduled to be removed from the program in a future release. If your app depends on a deprecated feature, it will break when that feature is removed.
Minor updates may include new features, generally, without breaking changes.
Patches are things like bug fixes or minor modifications.

New releases generally come with release notes that detail new features, changes, bug fixes, and especially breaking changes.

Install a specific version of a package

You can install a specific version number of a package using the below command:
npm install package_name@x.x.x
Example: npm install express@4.15.0

Update Packages

[5:23 Video timestamp]

To see if there are newer versions of your packages available enter:
npm outdated for local packages, or npm outdated -g for global packages.

[5:29 Video timestamp]
To update the package to the latest version based on the symbols in the package.json file enter:
npm update package_name
Or to update all packages enter
npm update

If you look at the package.json file in my-express-site, it will list the dependencies something like the below:

my-express-site/package.json

{
  ...
  "dependencies": {
    "cookie-parser": "~1.4.4",
    "debug": "~2.6.9",
    "ejs": "~2.6.1",
    "express": "~4.16.1",
    "http-errors": "~1.6.3",
    "morgan": "~1.9.1"
  }
}

The dependencies list the package name then the version.
Running the npm update command will have the following affect depending on the symbol used:

"pkg_name": "1.2.3" - No symbol before the version number. The package will not be updated at all.
"pkg_name": "~1.2.3" - Version prefaced with the ~ symbol. It will update to the latest patch version.
"pkg_name": "^1.2.3" - Version prefaced with the ^ symbol. It will update to the latest minor version.

To update to the latest major version, put @MajorVersion after the package name.
npm install express@5 will update to the latest version within version 5

Uninstall a package

[5:33 Video timestamp]

To uninstall a package enter:
npm uninstall package_name
To uninstall a global package enter:
npm uninstall -g package_name

Get information on a package

[5:39 Video timestamp]

To get information about a package go to npmjs.com and search the package name.
It will show the latest version, what its dependencies are if any. Dependencies will get installed if you install the package.
It will also have a link to the website which generally will have documentation about the package.

npm view: You can also get some information about a package by entering npm view package_name
For example: npm view express-generator

NPM (Video Tutorial)

NPM