rannikkohurri.net

npm is the standard package manager installed with Node.js. It consists of a command-line tool that gives you access to a world of javasckript libraries or so called packages.

It has become the de-facto standard for distributing modules (packages) for use with Node.js.

Yarn is an alternative package manager built by Facebook. It was released when npn was at v3 to address slowness among other things.

Today they're in general equally fast but as npm have focused on security a lot lately you should prefer npm to yarn these days.

# Useful Resources

Via a simple command-line interface you can easily install or even publish node modules (packages). You can also search for and upgrade installed packages. The package format is largely based on the same CommonJS format used by Node.js based on a package.json file with some additoinal fields.

# package.json

The package.json file stores information about your project and its dependencies, like name, version etc. You can initialize a new project by running npm init. This will run you through a series of questions for setting it up. Alternatively you can run npm init -y for default values that can be edited manually later.

# Local vs Global

Packages can be installd locally to the project or globally on the machine. Locally installed packages are placed inside a node_modules folder in your project root folder. You should in general prefer using locally installed packages. Global packages would typically be CLI-tools that you can use via the command-line directly. To install a package globally you add a -g flag.

  • Global node_modules directory under Unix-based systems is /usr/local/lib/node_modules or usr/local/lib/node.
  • Under Windows 7 and later typically at %AppData%\npm\node_modules.

If you are using the Node Version Manager, nvm, the node command is pointing to the version of node you have set as default with nvm. Under Windows typically C:\nvm\vernr\node_modules.

On Unix systems global installs typically requires a sudo command prefix. On windows run an elevated command line. Using nvm this is not required.

# The npx Option

If you don't want to install a lot of CLI-tools globally you can use npx if you have npm 5.2 or later.

The first part of the command installs the CLI-tool temporarily. It then executes the command part:

npx -p @angular/cli ng new myapp  # Create a new angular app
npx mocha                         # Run mocha tests without install
npx cowsay hello
1
2
3

You can also add npx commands to your npm scripts:

...
"scripts": {
  "createapp": "npx -p @angular/cli ng new myapp"
},
...
1
2
3
4
5

See also: The npm Blog and the Github page

# dependencies v.s. devDependencies

To install a package locally you use the npm install --save <pakagename> command. In more recent versions of npm the --save flag is added by default and can be omitted. The installed package along with the version installed will be added to the dependencies key in the package.json file.

To install a development dependency you use the npm install --save-dev <packagename> command. The installed package along with the version will be added to the devDependencies key in the package.json file.

if environment variable NODE_ENV is set to production, npm will ignore devDependencies when executing npm install.

# Semantic Versioning

The npm install command installs the latest version of a package. You can install a specific version using the @ sign followed by major and optionally minor and patch release versions. npm i -g eslint@5.2.0. Npm packages should follow Semantic Versioning.

Semantic versioning is made up of three numbers with a dot between. From left to right they represent the major, minor, and patch release version numbers. By default npm installs the version numbers prefixed with a caret symbol like "express": "^4.17.1". This symbol means that an npm install command would install the same major version but might upgrade to a later minor and patch release version when installing it on another machine.

  • Caret (^) -> All minor and patches OK to upgrade
  • Tilde (~) -> Only patches OK to upgrade

Remove the prefix character from the versions in package.json to always install a specific version.

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner, and
  3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

# package-lock.json

Running npm install in a new project also creates the package-lock.json file. While package.json is the input for the npm install command, package-lock-json can be seen as the output of what was actually installed. If you also provide the package-lock.json file in your project repo anyone installing packages will get the exact same versions you initially used.

# Useful Commands

npm help                    # Doc for package.json implementation
npm -v                      # Display version of npm

npm init                    # Create a new package.json file
npm init -y                 # Create a new package.json file no questions asked
npm i <pkg> <pkg2>...       # Install speificed package -S or --save is default in later vers
npm i -D|--save-dev <pkg>   # Install and save pkg as a dev-dependency in package.json. -D is shorthand for save-dev
npm i -g|--global <pkg>     # Install pkg globally. -g is shorthand for global
npm install -g npm          # Upgrade npm version
npm uninstall|remove pkg(s) # removes installed packages. remove can also be used
npm ls|list                 # Lists ASCII tree of installed packages and dependencies
npm ls|list --depth=0       # List root level locally installed packages. ls is shorthand for list
npm ls|list -g --depth=0    # List globally installed packages at the root level
npm outdated                # Check if we have outdated pkgs locally
npm outdated -g             # Check for globally outdated pkgs
npm install|update -g <pkg> # Update a globally installed package
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

See also the npm shorthand list

# NPM Cache

Clearing the npm cache can often be useful if you have unexpected problems with some library.

npm cache verify        # verify cache
npm cache clean --force # force npm to clean the cache
1
2

# Audit

You can use npm audit to verify that the packages you have installed are safe to use. The command will print a security report. Items will be listed with severity, what package the problem is in, in which version it was patched, what package it is a dependency of, the path to the source and a more info link. If it additionally contains a warning line, patching it could break your code.

Security warnings can be high, low or critical. The critical ones should be addressed asap. To resolve issues try running npm audit fix or alternatively upgrade the packages one-by-one.

# npm Scripting

# See also

Allows you to run commands via npm. Scripts are added to the scripts object in package json and contains a name and a command for each script. To run such a script you enter npm run scriptname. For a few select common scripts you can omit the run-part i.e. npm start, npm test.

"scripts": {
  "start": "nodemon ./index.js --exec babel-node"
}
1
2
3

From the command line you can then run npm start to execute the start script above.

# Useful Scripting Commands

npm test                    # Run test script in package.json. t is shorthand
npm run scriptname          # With no params lists available scripts.
npm version patch           # Bump version in package.json (major|minor|patch).
1
2
3

:todo: Add section on Deploying packages to npm

Updated: 8/17/2020, 4:16:52 PM

← Introduction →