# Awesome npm

> 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
- Packages
- Clients
- Tips
- FAQ
- Community
- Documentation
- Support
- Related

## Articles

- Small focused modules
- Unix philosophy and Node.js - Write programs that do one thing and do it well.
- Writing small modules
- Semver: A Primer (Must read!)
- Semver: Tilde and Caret
- Offline installation of npm packages
- Task automation with npm run
- How to use npm as a build tool
- Install npm packages globally without sudo on macOS and Linux
- Optimizing the footprint of an npm package
- The Art of Node - An introduction to Node.js and client-side development with npm.
- Why npm scripts? - An introduction to npm scripts with common packages and scripts, as well as a boilerplate project.

## Tools

### Web

- npms - Superb package search with deep analysis of package quality using a myriad of metrics.
- NodeICO - Package badges.
- Libraries.io - Package discovery.
- npm-stat - Statistics charts for packages.
- npmgraph - Visualization of dependencies.
- npm trends - Compare package download counts over time.
- npm-top - npm users by downloads.
- npm semver calculator - Visually explore what versions of a package a semver range matches.
- ghub.io - Redirects to the GitHub repo of an npm package.
- moiva - Discover and compare packages.

### Browser extensions

- Octo-Linker - Chrome extension to navigate across npm packages on GitHub with ease.
- npm-hub - Chrome extension to explore npm dependencies on GitHub repos.
- github-npm-stats - View npm download stats on GitHub.
- npm-search-update - Chrome extension to quickly search for dependencies and monitor changes from the npm registry.

### CLI

- zsh-better-npm-completion - Better ZSH completion for npm.
- npkill - Easily find and remove old and heavy node_modules folders.

## Packages

### Publishing

- np - A better `npm publish`.
- publish-please - Publish packages safely and gracefully.
- npm-release - Making releasing to npm so easy a kitten could probably do it™.
- pkgfiles - List all files which would be published in a package.
- release-it - Automate releases for Git repositories and/or npm packages. Changelog generation, GitHub/GitLab releases, etc.
- semantic-release - Fully automated package publishing.

### Registry

- npm-name - Check whether a package name is available on npm.
- package-json - Get the package.json of a package from the npm registry.
- latest-version - Get the latest version of an npm package.
- npm-keyword - Get a list of npm packages with a certain keyword.
- npm-user - Get user info of an npm user.
- npm-email - Get the email of an npm user.
- npm-user-packages - Get packages by an npm user.
- dpn - Get the dependents of a user’s npm packages.
- npm-stats - Get data from an npm registry.
- npm-cli-login - Log in to npm.
- nrm - Registry manager.
- npm-register - Easy to set up and maintain npm registry and proxy.
- verdaccio - Lightweight private npm proxy registry.
- cloudsmith - A fully managed package management SaaS with support for public and private npm registries (and many others).

### Other

- npm-home - Open the npm page of a package.
- gh-home - Open the GitHub page of a package.
- david - Check if your package dependencies are out of date.
- npm-check - Check for outdated, incorrect, and unused dependencies, as well as interactive update.
- npm-upgrade - Update outdated npm dependencies interactively.
- npm-shrinkwrap - A consistent shrinkwrap tool.
- npm-windows-upgrade - Upgrade npm on Windows.
- generator-nm - Scaffold out an npm package.
- package-up - Find the closest package.json file.
- read-package-up - Read the closest package.json file.
- normalize-package-data - Normalize package metadata.
- package-config - Get namespaced config from the closest package.json.
- npm-run-path - Run locally installed binaries in the terminal by name like with global ones.
- local-npm - Use npm offline.
- npe - CLI for inspecting and editing properties in package.json.
- engine-deps - Manage Node.js version specific dependencies with ease.
- enpeem-search - Search packages by scraping the npm web search.
- npm-issues - Search known issues of all your packages at once.
- john - Make npm3’s flat dependencies easier to find and sort.
- ntl - Interactive CLI menu to list & run npm tasks.
- decheck - Explore dependencies of npm packages in the command-line.
- shrinkpack - Lock down your dependencies and install offline.
- redrun - Expand scripts from package.json to improve execution speed.
- package-size - Get the bundle size of an npm package.
- synp - Convert yarn.lock to package-lock.json and vice versa.
- npm-run-all - CLI tool to run multiple npm-scripts in parallel or serial.
- onchange - Watch files and folders and run a command when something changed.
- cli-error-notifier - Sends native desktop notifications when npm scripts fail.
- luna - App to manage npm dependencies.
- emma-cli - Interactive CLI package search utility.
- lockfile-lint - Lint lockfiles for improved security and trust policies to mitigate malicious package injection and insecure lockfile resources.

## Clients

- yarn - Fast, reliable, and secure dependency management.
- npm - The official client.
- pnpm - Fast, disk space efficient package manager.

## Tips

### Update to the latest npm version

    $ npm install --global npm

Windows users, read more.

### Command aliases

- `npm i` → `npm install`
- `npm i -D` → `npm install --save-dev`
- `npm t` → `npm test`
- `npm it` → `npm install && npm test`
- `npm r` → `npm uninstall`
- `npm un` → `npm uninstall`
- `npm up` → `npm update`

### 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 --package=node-bin@6.11.0 -- 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 chalk@1.0.0

### 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:

- https://wzrd.in/standalone/object-assign
- https://wzrd.in/standalone/object-assign@4.0.0

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

## FAQ

- Check in node_modules vs. shrinkwrap
- What is the difference between Bower and npm?
- What does `^` mean in package.json versioning?
- Find the version of an installed npm package
- What’s the difference between dependencies, devDependencies, and peerDependencies in package.json?

## Community

- `#npm` on Freenode
- Stack Overflow
- Reddit
- Twitter
- Blog

## Documentation

- Official
- Troubleshooting
- Semantic versioning
- Fixing npm permissions
- package.json
- npm run script
- Stats API

## Support

- npm.community
- Twitter
- Contact form

## Related

- awesome-nodejs

npm.md Github