Init a project

A file named package.json allows package management in your project. To create it by answering prompts run npm init, add -y if you want to create it instantly, skipping questions.

Setting default config values

npm set init-author-name 'Your Name' will set a default author name whenever you run npm init again. More npm set init-<flag> exist, e.g. to set default email, license and others. Run npm get init-<flag> to read a set value and npm config delete init-<flag> to delete a setting. Those setting will be stored in .npmrc file in your user diretory.

Installing packages and the role of package-lock.json

npm install or npm i will install packages with versions specified in package-lock.json and ignore packages specified in package.json. If package-lock.json does not exist, this command will download the latest version, add it to package.json with a caret (^, explained later) and create the lock file for you. You should commit package-lock.json to your source code repository, so each developer will install the same version as specified in that file.

Installing specific package versions

Run npm i package@1.2.3 to install a specific package version. Note that this will still add ^1.2.3 (with the caret) to your package.json, just as if you had omitted the specific version. A package defined as ^1.8.0 might install 1.10.2 when npm i is run again in the future and no package-lock.json exists. Having a package version defined as ~1.8.0 will only update to the latest patch version such as 1.8.3. Replacing any version with x or * in package.json will install the latest version of all available versions. To prevent any caret or tilde you can add --save-exact to save the exact version in package.json.

Running npm i package@1 or npm i package@1.x will install the latest version with major version 1. Running npm i package@1.2 or npm i package@1.2.x will install the latest version with major version 1 and minor version 2. A range like npm i package@">=1.2 <1.4" also works.

Add -g to install a package globally, which is useful if you want to run a package from the command line.

npm shrinkwrap locks down the version of a package’s dependencies so that you can control which versions of each dependency will be used when your package is installed.

Saving, uninstalling and updating packages

npm i <package-name> -D or --save-dev will write the dependency as dev dependency in package.json.

npm uninstall <package> or npm rm, npm un or npm r will remove the package. Add -g to uninstall global packages.

Run npm update to update all your packages according to the version definitions in package.json.

If you installed a package but did not --save it, then you can remove all those unsaved packages with npm prune. npm home lodash opens the homepage of that package and npm repo opens the repository of the package.

Listing packages

npm list or npm ls will list all installed packages in your project including their dependencies. Add --depth 1 to limit the display of dependencies to one level or just display the ones that you directly installed with --depth 0, similar to what your package.json shows. Add --long for a description of packages. Add --json for JSON output. Use the flag --parseable to list the directories of dependencies. Limit the display of prod packages with --prod or --dev. Add -g to see globally installed packages.

npm xmas and npm visnup are easter eggs.

npm scripts

npm scripts are executable commands that can be defined in package.json under the scripts property.

npm run lists all available scripts. There are two types of scripts, lifecycle and custom scripts. Lifecycle scripts use pre-defined keywords, such as test, start, stop, restart (and most of them have variants using pre– or post-, e.g. prestart, poststart). Custom scripts need to be executed with npm run (e.g. npm run custom-test), but lifecycle scripts can also be executed without run (e.g. npm test is the same as npm run test).

The script that runs your application (e.g. that starts your server) should be specified as start like:

  "scripts": {
    "start": "node index.js"
  },

So it can be executed with npm start.

Any command in your operating system’s PATH and in node_modules/.bin are available when defining scripts.

Passing arguments to commands within a script

Let’s say you have a script “compile”:

"scripts" : {
  "compile" : "tsc"
}

and you want to pass --init argument to the tsc within the compile script from the command line, then you have to add -- as a delimiter first, like that:

npm run compile -- --init

Script hooks

A hook is any script that is run automatically before or after another script. For example, if you define a prestart script then it will get executed every time you run npm start. That can be useful when you want to compile your code in prestart before start.

You can call npm scripts within another npm script. And you can run multiple commands within one script:

"scripts" : {
  "prestart" : "echo Running prestart && npm run compile",
  "compile" : "tsc"
}