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.
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 “http://bakaitis.com”
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.
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=falsedisables 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
--saveflag will save the package name to the
package.json. This saves an editing step and when installing many packages at the same time, helps reduce
homanhuman error. note: using the
-Sswitch is a shorter, equivalent version of –save, resulting in
npm install <package> -S
save-dev– As with
--save-devwill save the package to the
package.json. Note the
npm install <package> -Dstreamlines 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
PATHvalues, 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.
npm config set <key> <value> [-g|--global]
npm config get <key>
npm config delete <key>
npm config list
npm config edit
npm get <key>
npm set <key> <value> [-g|--global]
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:
npm install <package> --depth=0
npm ls -g --depth=0
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:
npm config set depth 0
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). .
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.
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:
.npmrcin my home directory is most important because that “per-user” file applies to all of the projects I work upon
.npmrcin 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
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.