Table of Contents

• Commands
  • init
  • install
  • update
  • list
  • config
  • run-script
• package.json
  • package-lock.json
  • files
  • scripts
  • semver
• How-to
  • publish
  • List globally installed packages
• Topics
  • dependencies, devDependencies, peerDependencies
  • Scoped packages

Commands

init

$ npm init
# prompt some information
# then, creates 'package.json'

# use only defaults: --force and --yes are same
$ npm init -f  # --force
$ npm init -y  # --yes

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

install

local

<cwd>/node_modules

global

{prefix}/lib/node_modules

# global
npm install npm --global

# specify a version
npm install underscore@1.8.2

npm install # dependencies + devDependencies
npm install --only=prod
npm install --only=dev

update

npm update underscore

• Update all the packages listed to the latest version, respecting semver.

list

$ npm list --global
$ npm list --global --depth=0

config

$ npm config list                                                                                                                                                                                              1 ↵

; cli configs
metrics-registry = "https://registry.npmjs.org/"
scope = ""
user-agent = "npm/5.6.0 node/v9.4.0 darwin x64"

; builtin config undefined
prefix = "/usr/local"

; node bin location = /usr/local/Cellar/node/9.4.0/bin/node
; cwd = /Users/yeonghoey
; HOME = /Users/yeonghoey
; "npm config ls -l" to show all defaults.

To change prefix:

$ cd ~ && mkdir .node_modules_global
# Creates ~/.npmrc
$ npm config set prefix=$HOME/.node_modules_global

run-script

• npm run <cmd> set their customized signal handler. (code) (ref:close)
• It seems that npm propagates the signal to the spawned process (code)
• As a result, the spawned process receives the signal twice (as a member of theprocess group and the signal sent by npm)
• It seems that it's because of compatability for some OS not propgates signals to the process group or something.

package.json

{
  ...
  "dependencies": {
    "underscore": "^1.8.3"
  }
}

The caret (^) at the front of the version number indicates that when installing, npm will pull in the highest version of the package it can find where the only the major version has to match (unless a package-lock.json file is present), In this case, anything below v2.0.0.

devDependency by specifying a --save-dev flag. devDependencies are packages used for development purposes, for example for running tests or transpiling code.

private: true to prevent accidental publication of private repositories.

package-lock.json

package.json can trump package-lock.json whenever a newer version is found for a dependency in package.json. If you want to pin your dependencies effectively, you now must specify the versions without prefix, that means you need to write them as 1.2.0 instead of ~1.2.0 or ^1.2.0.

files

1. If the files array is omitted, everything except automatically-excluded files will be included in your publish.
2. If you name a folder in the array, then it will also include the files inside that folder (unless they would be ignored by another rule in this section.).

Inlcuded by default

• package.json
• README
• CHANGES / CHANGELOG / HISTORY
• LICENSE / LICENCE
• NOTICE

Excluded by default

• .git
• CVS
• .svn
• .hg
• .lock-wscript
• .wafpickle-N
• .*.swp
• .DS_Store
• ._*
• npm-debug.log
• .npmrc
• node_modules
• config.gypi
• *.orig
• package-lock.json (use shrinkwrap instead)

scripts

Additionally, arbitrary scripts can be executed by running npm run-script <stage>. Pre and post commands with matching names will be run for those as well (e.g. premyscript, myscript, postmyscript)

Executables installed (in node_modules/.bin) will be added to the PATH for executing the scripts.

It seems that people often use <verb>:<sub> for custom scripts like:

"scripts": {
  "start:dev": "webpack-dev-server"
}

semver

# Tilde Ranges: Allows patch level changes
~1.2.3 := >=1.2.3 <1.3.0

# Caret Ranges: Allows patch and minor level changes
^1.2.3 := >=1.2.3 <2.0.0

How-to

publish

List globally installed packages

npm list --global --depth=0

Topics

dependencies, devDependencies, peerDependencies

• dependencies are installed on both:
  • npm install from a directory that contains package.json
  • npm install $package on any other directory
• devDependencies are:
  • also installed on npm install on a directory that contains package.json, unless you pass the --production flag
  • not installed on npm install "$package" on any other directory, unless you give it the --dev option.
  • are not installed transitively. (E.g. we don't need to test B to test A, so B's testing(dev) dependencies can be left out.)
• peerDependencies are:
  • For some sub packages like plugins of something(e.g webpack and babel-loader)
  • They correctly work with proper versions of the host(peer) dependency(webpack v1.0.0)
  • Causes error if a different verion of peer dependency installed
  • Not automatically installed

Scoped packages

@somescope/somepackagename