Awesome npm Awesome

Awesome npm resources and tips

npm is a package manager for the JavaScript programming language and comes bundled in the Node.js runtime.

Please read the contribution guidelines before contributing.

Contents

Articles

Tools

Web

Browser extensions

CLI

Packages

Publishing

Registry

Other

Clients

Tips

Update to the latest npm version

$ npm install --global npm

Windows users, read more.

Command aliases

Shell aliases

Speed up your common npm tasks.

In your .zshrc/.bashrc:

alias ni='npm install'
alias nid='npm install --save-dev'
alias nig='npm install --global'
alias nt='npm test'
alias nit='npm install && npm test'
alias nk='npm link'
alias nr='npm run'
alias ns='npm start'
alias nf='npm cache clean && rm -rf node_modules && npm install'
alias nlg='npm list --global --depth=0'

Don't add to package.json when installing

By default npm adds packages you install to the dependencies field in package.json (since v5). You can prevent this by specifying the --no-save flag. You can add a package to devDependencies with --save-dev/-D:

$ npm install --save-dev ava

Run scripts

You can easily run scripts using npm by adding them to the "scripts" field in package.json and run them with npm run <script-name>. Run npm run to see available scripts. Binaries of locally install packages are made available in the PATH, so you can run them by name.

{
	"name": "awesome-package",
	"scripts": {
		"cat": "cat-names"
	},
	"dependencies": {
		"cat-names": "^1.0.0"
	}
}

$ npm run cat
Max

All package.json properties are exposed as environment variables:

{
	"name": "awesome-package",
	"scripts": {
		"name": "echo $npm_package_name"
	}
}

$ npm run name
awesome-package

Passing options to commands

You can pass options to the command you are using in your npm script by adding -- --flag like in the example below. The -- marks the end of options parsing, so npm run will just ignore it and pass it to the command.

{
	"name": "awesome-package",
	"scripts": {
		"xo": "xo",
		"xo:fix": "npm run xo -- --fix",
	}
}

Adding the -- --fix option is like executing xo --fix.

Silent option

npm run has a --silent option which is especially useful when combining npm scripts.

Imagine you have a setup for linting your JavaScript files like the following:

{
	"name": "awesome-package",
	"scripts": {
		"xo": "xo",
		"xo:fix": "npm run xo --silent -- --fix",
	}
}

Using the --silent option reduces the output in the terminal. See this comparison.

Lifecycle scripts

npm comes with predefined lifecyle scripts which are excuted under specific conditions if they are defined in your package.json.

{
	"name": "awesome-package",
	"scripts": {
		"prepublishOnly": "nsp check"
	},
	"devDependencies": {
		"nsp": "^3.0.0"
	}
}

This will be executed automatically before your npm package is published to the registry via npm publish to check for known vulnerabilties in your dependencies.

Note: prepublishOnly is available since npm v4.0.0. See npm docs.

npm start and npm test

npm start and npm test are also lifecycle scripts but are not executed automatically.

{
	"name": "awesome-package",
	"scripts": {
		"start": "node server.js",
		"test": "ava"
	},
	"devDependencies": {
		"ava": "^1.0.0"
	}
}

Therefore they can be executed simply with:

$ npm test
$ npm start

pre and post scripts

These are special lifecycle scripts which can be used to run scripts automatically in sequence.

{
	"name": "awesome-package",
	"scripts": {
		"pretest": "eslint .",
		"test": "ava"
	},
	"devDependencies": {
		"eslint": "^4.19.0",
		"ava": "^1.0.0"
	}
}

$ npm test

This will lint your files before running your tests. The tests will not run if linting fails. Or more generally spoken: the following script won’t be executed if one of the scripts running in sequence exits with an exit code other than 0.

Note: pre and post scripts can also be used for your custom npm scripts. So npm run foo will also run prefoo and postfoo if defined.

Run script with npx

npm comes bundled with npx (Since v5.2.0) — a tool to execute package binaries. Each command is executed either from the local node_modules/.bin directory, or from a central cache, installing any packages needed in order for <command> to run.

{
	"name": "awesome-package",
	"dependencies": {
		"cat-names": "^1.0.0"
	}
}

If the binary is already installed, it will be executed from node_modules/.bin.

$ npx cat-names
Max

But if the binary is missing, it will be installed first.

$ npx dog-names
npx: installed 46 in 3.136s
Bentley

Run commands with different Node.js versions

With npx (Comes bundled with npm v5.2.0 or newer) and the node-bin package, you can easily try out code in different Node.js versions without having to use a version manager like nvm, nave, or n.

$ npx [email protected] -- node --version
v6.11.0

Link local packages

Sometimes it can be useful to have a local version of a package as a dependency. You can use npm link to link one local package into another. Run npm link in the package you want to use. This creates a global reference. Then go into your original package and run npm link <package-name> to link in the other package.

$ cd rainbow
$ npm link
$ cd ../unicorn
$ npm link rainbow

You can now use rainbow as a dependency in the unicorn package.

Install a package from GitHub

npm supports using a shorthand for installing a package directly from a GitHub repo:

$ npm install sindresorhus/chalk

Let's target a specific commit as the main branch is a moving target:

$ npm install 'sindresorhus/chalk#51b8f32'

Specify either a commit SHA, branch, tag, or nothing.

You can also install Git dependencies with semver: (Requires npm v5 or newer)

$ npm install 'sindresorhus/chalk#semver:^2.0.0'

Install a specific version of a package

$ npm install [email protected]

List top-level installed packages and their version

$ npm ls --depth=0

Command help

Get help docs for a command:

$ npm help <command>

Example:

$ npm help install

Standalone version of a package

Quickly get a standalone version of a package that is browserified and usable in the browser.

https://wzrd.in/standalone/<package-name>[@<version>]

Examples:

Great for prototyping, but download the file or use Browserify yourself for production.

FAQ

Community

Documentation

Support