npm Commands and Features You Should Know

I love the npm CLI. Sorry, not sorry. npm has caught some flak over the years for one reason or another . Nevertheless, its command line interface is ubiquitous. It’s the foundation for most modern build systems and it’s still the most popular solution for managing project dependencies.

Even the new GitHub Package Registry only supports npm as a client for JavaScript packages (at least for now). With all that weight behind it, it’s a tool worth knowing well. The following is a list of npm commands that will make your daily trek through the web dev landscape more enjoyable.

Let npm Do the Work

completion

Did you know npm supports autocompletion? Run npm completion in a terminal and it will output a bash completion script. If you use an out-of-the-box command line framework, like oh-my-zsh , then this may be taken care of for you . But if not, appending this script to your .bashrc ( or similar ) is all you need. Thanks to the CLI, it’s pretty straightforward.

$ npm completion >> ~/.bashrc

start

A lesser known aspect of the start command is that it doesn’t require a start script to be defined in package.json. npm was initially designed with Node.js projects in mind. After all, npm stands for node package manager . So it should be no surprise that by default, start will run a server.js file in the root of your project. The more you know. :rainbow:

explore

You can run npm commands against packages in your node_modules by invoking the explore command. For instance, you can verify which version of a package you have installed without sifting through your package-lock (or your undoubtedly massive node_modules ).

$ npm explore typescript -- npm version

# output
{ typescript: '3.6.2', ... }

edit

If you want to inspect or modify the contents of a package, again, please do skip the node_modules diving. Instead, you can lean on the edit command.

$ npm edit globby

This will pop open an editor with the given package contents so you can inspect or edit them. Make sure you have $EDITOR set in your environment because it will use that to open the package.

Learn About Your Packages

view

You can get the latest (or any) package info with the view command.

$ npm view react

# output
[email protected] | MIT | deps: 3 | versions: 218
React is a JavaScript library for building user interfaces.
[https://reactjs.org/](https://reactjs.org/)
dist
.tarball:[ https://registry...react-16.9.0.tgz](https://registry...react-16.9.0.tgz)
.shasum: 40ba2f...85c4f7aa
.integrity: sha512-+7LQn...e66S1w==
.unpackedSize: 232.7 kB
maintainers:
- acdlite
- brianvaughn
- gaearon
- etc
dist-tags:
alpha: 16.9.0-alpha.0
canary: 0.0.0-8d5403877
latest: 16.9.0
next: 16.9.0
unstable: 0.0.0-0c756fb-f7f79fd
published a month ago by acdlite

This outputs a lot of good info, like the latest version, tagged releases, package resolution, and fingerprints.

repo

Looking for the repo of a package so you can open an issue or make a sweet contribution? This command will crack open your browser and take you there straight away.

$ npm repo webpack

docs

The docs command works similar to repo but it will do it’s best to find the canonical documentation site for a package.

npm docs react

This will open the React documentation home page.

Shorthands and Flags

Like npm i stands for npm install , there are other phonetic shorthands that exist, including a shorthand for test and combinations of test and install . These quick keystrokes can save you whole seconds over the course of a year—you’re welcome.

npm i
npm t
npm it
npm ci
npm cit

If you read the npm docs you’ll discover many options to the various commands. Here are just a few that I find extra useful and/or use often.

• npm init -y - the flag is short for --yes , use this if you want to initialize a project quickly, without the question/answer flow. It will answer “yes” to all questions, taking the defaults.
• npm install -D - the flag is short for --save-dev
• npm install -E - the flag is short for --save-exact , use this when you need an exact version as opposed to a semver range
• npm run <script> --if-present - this will run the given script only if present. Useful if you want to run a package script against an unknown set of packages. Think continuous integration or local setup scripts.

Versioning and Publishing

version

If you’re new to publishing, you may find yourself incrementing package versions manually. You don’t have to do that. The version command can handle many of the bumps for you.

$ npm version patch

This will increment that patch version in yourpackage.json. But it will also update the version in your package-lock, commit it all, and create a tag (with the new version name by default). This all happens in one command. Use it.

npm can also handle prerelease versions . This is useful when you want to validate packages in an ecosystem before promoting to a stable version.

$ npm version premajor --preid alpha

Given a starting version of 0.1.0 , the above command will result in a version of 1.0.0-alpha.0 . The --preid argument is optional. Without it, you would get version 1.0.0-0 . Note: Identifiers can only contain ASCII alphanumerics and hyphen [0-9A-Za-z-].

Subsequent calls to npm version prerelease will bump the last number at the end of the id. Once your prerelease has been tested, throw any non-prerelease version commands at it, such as npm version major . Voilà, the version will be promoted to 1.0.0 , and semver says it’s stable. :sparkles:

pack

Ever wonder what you’re actually delivering in your npm package? Use the pack command to produce a tarball of your package as it would be published to the registry.

$ npm pack

# output
npm notice
npm notice :package: [email protected]
npm notice === Tarball Contents ===
npm notice 436B  dist/main.js
npm notice 1.7kB package.json
npm notice 246B  README.md
npm notice 581B  CHANGELOG.md
npm notice === Tarball Details ===
npm notice name:          my-awesome-package
npm notice version:       1.0.0
npm notice filename:      my-awesome-package-1.0.0.tgz
npm notice package size:  1.1 kB
npm notice unpacked size: 2.8 kB
npm notice shasum:        2830767a6...4ac5d78d64
npm notice integrity:     sha512-1L...YN4uFX9Q==
npm notice total files:   4

You can actually install straight from a local tarball to see what you get.

$ npm i my-awesome-package-1.0.0.tgz

link

What if you need to install a local package and iterate on it from a consuming app? the link command has your back. It creates a symlink from a package in your node_modules to a local version of said package. The link command works two different ways depending on whether you’re running it from the source package or a consuming app.

To link a local package, first run npm link with no arguments in the root directory of the source package. Then run npm link <package-name> in the root directory of the consuming app. You will now have a symlink between the two, and updates to the source package will be automatically reflected in node_modules . Keep in mind that if the source package requires a build step, then you’ll have to run that build when making changes. Running npm install in the consumer will remove any established link.

publish

When publishing prerelease versions, it’s useful to tag them. This makes them easy to install for consumers. It’s common to tag the newest prerelease as next .

$ npm publish --tag next

Any version published with the above command will be installable with npm i <package>@next .

deprecate

If you want to notify package consumers of deprecations, you can use deprecate . The command takes an optional message that can help communicate specifics. A notice will be displayed to users who install a deprecated package.

$ npm deprecate [email protected] "please use 1.0.1"

Bonus Utilities

npm knows where it is. There are commands to output important paths that you may want to take advantage of in different scenarios.

• npm prefix - resolves to the closest parent directory to contain a package.json file or node_modules directory. Usually the root of your project.
• npm bin - resolves to ./node_modules/.bin . This is where executables are kept for locally installed packages.
• npm root - the effective node_modules directory

Add the global flag to any of these and you can read the same paths as applied to your globally installed version of npm .

$ npm prefix -g

/usr/local

$ npm bin -g

/usr/local/bin

$ npm root -g

/usr/local/lib/node_modules

Much like Homebrew , npm has a doctor command. It will confirm the following:

• Node.js and git are executable by npm.
• The primary npm registry is available.
• The directories used by npm exist and can be written by the current user.
• The npm cache exists, and the package tarballs within it aren’t corrupt.

Wrap Up

This has been an overview of the npm commands and features that I find most useful. But there are certainly more that aren’t covered in this article. You can always check the full CLI documentation or use the tool itself, npm -l will display full usage info in your terminal.