npm Configuration Basics

npm logoConfiguration Basics

Proper npm configuration makes package management easier and faster. Unfortunately, documentation is spread over several pages and no single official resource summarizes configuration options and best practices.  Like git, npm provides a solid set of configuration defaults and when no default exists, prompts users for values. This works great in most situations, but as you use it more often, using the same config override over and over, it is  time to make more lasting configuration setting changes.

Useful Settings

Configuration can set via the CLI or by editing .npmrc that npm reads when it executes.  There are sections further down that explain the mechanics, but for now, let’s review some of the more useful and important settings.

project init defaults

If you frequently start new projects, answering the prompts for the init command can become tedious.  Because the answers for initiating a new project are typically slow to change, adding these settings can simplify things.

  • init-author-name – takes a string for the author’s name
  • init-author-email – takes a string for the author’s email
  • init-author-url – takes a URL for the author, something like “”
  • init-license – the license value must match one from a set number of valid license descriptions, found on the SPDX site.  If you want to use a license not found in the list, use the string “SEE LICENSE IN <filename>”.  Values must be on the SPDX list or use the “SEE LICENSE” phrasing.
  • init-version – used to set the default version, which is 1.0.0 by default.  The default version must be parsable by node-semver or things will puke.

install settings

  • depth – when an install finishes or a list of packages generates, the result is a huge tree of all packages and dependencies.  Parsing this by eye is tough, but this can be simplified by setting depth equal to zero.  Depth takes an integer value, so if you like to see one level of nested dependencies, that’s also easy to manage.
  • progress – the larger the project, the longer first package installation will take.  npm offers a progress bar as visual feedback but for awhile, the progress bar actually slowed things down. At that time, disabling it resulted in faster installations.  For the superstitious or for people who switch to another window, setting progress=false disables the bar.
  • save – OK, this is not a configuration setting you’ll want to save, but it’s an important one to understand.  When installing, using the --save flag will save the package name to the "dependencies" array in package.json.  This saves an editing step and when installing many packages at the same time, helps reduce homan human error.  note: using the -S switch is a shorter, equivalent version of –save, resulting in npm install <package> -S
  • save-dev – As with save, save-dev or --save-dev will save the package to the "devDependencies" array in package.json.  Note the save-dev synonym of -D.  npm install <package> -D streamlines the call.
  • prefix – Knowing this one can save a ton of time when troubleshooting global installation problems.  Prefix takes a path as a string defining where global packages are saved.  Using this, plus your OS PATH values, can be a very quick check (and point to a fix) to ensure that global packages are (a) being installed where you think and (b) that location is reachable via the path.

Using the npm Command Line

Settings can be saved at the command line with the config command. Using npm config help outputs some useful information to the console, but the following are a good reference for using it to set preferences.

Example 1: setting depth to zero for one install

Note that settings can also be passed into npm at the command line by preceding the key name with a double-dash, an equal sign, and then the value.  For example, if I was using default values or I’m on a co-workers machine and the depth setting isn’t saved, I could set the depth as such:

In the first illustration above, when the install finishes, it will show a tree of packages that only include the top-level packages.  Or, in other words, it will only show the packages I explicitly installed an none of the dependencies within.

In the second illustration, I am using npm’s ls command to show all globally (-g) installed packages with a depth of zero.

This is useful with things like --progress=false where you normally want to see the progress bar, but perhaps you don’t care or it’s a huge install and you don’t want to risk any side effects the bar may introduce.

Example 2: persisting the depth to zero

As an example, because I literally never read beyond the top level package, I used the following to ensure that the depth setting is always zero unless I override:

And now, I never see more than what I installed (and what might be extraneous).

Listing the current settings

npm config list dumps the current settings that differ from the default values.  The custom settings are found in an .npmrc file(s).  .

Note that npm config list is especially useful when troubleshooting problems with installing packages globally.  A common problem, more often on Windows installations, has the global prefix path pointing to a directory that isn’t in the OS PATH.  As such, while npm installs successfully and listing globally installed packages returns the expected results…global packages won’t run.  Knowing about prefix can make extremely quick work of this issue.

Editing .npmrc

npm stores settings in one of several.npmrc files.  Documentation for the file explains each version of .npmrc and file intent.  My limited use suggests:

  • the .npmrc in my home directory is most important because that “per-user” file applies to all of the projects I work upon
  • .npmrc in a project directory benefits more advanced use cases than this note covers
  • there is a global but, honestly, you’ve got me what it means or does…
  • and then there are the default settings (see npm config list, above)

The command line npm config offers the the easiest way to get data into or or out of .npmrc.

For larger changes, edit the file with your favorite text editor.   Note the file format differs from the command line syntax. Also, call npm config list after editing manages reduces the risk of a typo by printing all changes to the console for easy review.


Basic configuration settings make new project and package management a bit easier.  The prefix setting is valuable when troubleshooting global package issues, quickly finding disparities between where npm is installing the packages and the paths where the OS is looking for files.

While relevant to most npm users, the full list of settings illustrates how configuration options meet the needs of users in larger or complicated development situations. A quick read of the full list can mean the difference between multiple work-around steps or a single call or command.