Comprehensive Guide to npm-docs, npm-doctor, and npm-edit Commands

In the previous tutorial we looked at npm's dedupe, deprecate and dist-tag cli options, the tutorial you are about to read will examine the workings of npm's docs, doctor and edit cli options.

npm-docs

The npm-docs provides the documentation for a package in the web browser.

Synopsis

npm docs [<pkgname> [<pkgname> ...]]
npm docs .
npm home [<pkgname> [<pkgname> ...]]
npm home .

Description

This command will attempt to guess the most likely location for a package's documentation URL, and then it will try to open it using the -browser config param. Multiple package names can be passed at once. If you don't provide a package name, it searches for a package.json in the current folder and then uses the name property.

Configuration

browser

• Default: Windows: "start", OS X: "open", Others: "xdg-open"
• Type: String

This is the browser that is called by the npm docs command to open websites.

Registry

This is the base URL of the npm package registry.

• Default: https://registry.npmjs.org/
• Type: url

Npm-doctor

his command is used to check your environments.

Synopsis

npm doctor

Description

If you want to run checks to ensure that your npm installation has what it needs to manage your JavaScript packages, you need to use npm doctor.

Although npm is mostly a standalone tool, it has some basic requirements that has to be met:

• Node.js and git should be executable by npm.
• Npm's primary registry, registry.npmjs.com, or another service that utilizes the registry API, is available.
• The directories that npm makes use of, node_modules (both locally and globally), exist and the current user can write it.
• There is an npm cache, and the package tarballs that is within it are not corrupt

If all these are not working properly, npm may not function properly. Most of the issues are often attributable to things that are outside of the npm's code base, hence, npm doctor will confirm that the installation is in a good state.

Additionally, issues may arise due to the use of old versions of npm. This is because npm is constantly improving, and running npm@latest is better than using an old version.

Npm doctor will verify that the requirements listed above are met and if there are recommended changes, it will display them.

Npm ping

Npm will install from the primary npm registry by default. npm doctor will hit a special ping endpoint within the registry. You can also check this with npm ping. If the check fails, it could be that you are using a proxy that needs to be configured, or you could consider asking your IT staff to give registry.npmjs.org HTTP access.

This check will be done against whoever registry you have configured (this can be seen by running npm config get registry), this check may also fail if you are using a private registry that doesn?t support the /whoami endpoint that is supported by the primary registry.

npm -v

In most cases, the best verison of npm to use will be the latest long term support (LTS) release. If you want access to new ECMAscript features or the bleeding-edge changes to Node's standard library, you can use a newer version. You might be running an older version due to enterprise change policies. However, the npm team will always recommend that most users run the LTS of Node.js.

npm config get registry

This is the part of npm doctor that lets you troubleshoot your project to know if you are using the default registry specified by npm.

which git

Although, it is documented in the README, it might not be obvious that npm requires Git to be installed to do most of the things that it does. Also there are scenarios especially on windows where Git is not accessible via your PATH so that npm can find it. The which git command ensures that Git is available.

Permissions checks

• Your cache should be readable and writable by the user running npm.
• Global package binaries should be writable by the user running npm.
• Your local node_modules path, if you are running npm doctor with a project directory, should be readable and writable by the user running npm.

Validate the checksums of cached packages

When you publish an npm package, the publishing process will generate a checksum that npm uses at install time to verify that the package didn't get corrupted in transit. npm doctor will use these checksums to validate the package tarballs in your local cache (you can see where that cache is located with npm config get cache, and see what is in that cache with npm cache ls - probably more than you were expecting!). If there are corrupt packages in your cache, you probably have to run npm cache clean and reset the cache.

npm-edit

This will edit an installed package.

Synopsis

npm edit <pkg>[@<version>]

Description

This will open the package folder in the default editor (or whatever you have configured as the npm editor config )

Once it has been edited, the package will be rebuilt so as to pick up any changes in compiled packages.

For example, you can run npm install connect to install connect into your package, and then run npm edit connect to make a few changes to your locally installed copy.

Configuration

editor

• Default: EDITOR environment variable if set, or "vi" on Posix, or "notepad" on Windows.
• Type: path

This is the command to run for npm edit or npm config edit.

Previous: Comprehensive Guide to npm-dedupe, npm-deprecate, and npm-dist-tag Commands.
Next: Understanding npm-explore, npm-help, and npm-help-search Commands.