The Ultimate Guide to Configuring NPM

Introduction

The Node Package Manager, or npm, is one of the best parts about Node, in my opinion. Package management can really make or break a language, so ensuring that it is easy to use and flexible is extremely important.

Throughout my use of Node, I only ever knew the basic npm commands like save, install, and publish, and even then I didn't really know the optional parameters that went along with them. After reading some of the help documentation recently, I thought it would be helpful to write up details on as many of the npm configurations as possible. Not only do I think this could be helpful to the readers, but it was extremely helpful to me to look through all the different flags/parameters and to actually test them out. I ended up learning a lot about npm that will help me out a bunch in the future.

For the most part, I tried to write up a unique description of each parameter (different from the help docs). Hopefully that way if the help docs confuse you (or don't have enough information), my description will give some more insight into whatever you're looking for. I'll also be adding examples of some of the more confusing parameters, so if you know how to use some of the more undocumented options, like searchopts, I'd love to see an example!

Setting Parameters

Unless otherwise noted, all of the parameters below can be set through a few different methods, each of which I'll describe briefly here. Depending on your use-case, utilize the different purposes for things like testing, project-specific configuration, global configuration, etc.

npmrc Files

npm allows you to use a few different rc files, much like ~/.bashrc, to set your configurations. The four locations where the files may reside are:

• Per-project config file: /path/to/my/project/.npmrc
• Per-user config file: ~/.npmrc
• Global config file: $PREFIX/etc/npmrc
• Built-in npm config file: /path/to/npm/npmrc

https-proxy=proxy.example.com
init-license=MIT
init-author-url=http://stackabuse.com
color=true

The file you use should depend on the parameter and scope you're wanting to set. So, for example, you'd probably want to set https-proxy in the global npmrc file as opposed to the project-level npmrc file since all projects on the system will need the proxy settings.

Environment Variable

There are a few environment variables that npm will use over parameters set locally (or in an npmrc file). Some examples are NODE_ENV and HTTPS_PROXY. You can also set any npm parameter by prefixing an environment variable with npm_config_. So that way you can do things like export npm_config_registry=localhost:1234.

A lot of people are used to using environment variables for configuration, so this should be familiar to them. For example, a great way to configure a Docker instance is to set environment variables from the dockerfile.

Flags on Command Line

Not all parameters need to be permanently set in a file or environment variable. Many of them can be used within an npm command as a flag, prefixed with --.

For example, if you're installing a new package from the registry and want to save it to your package.json file, you'll want to use the --save flag, but that might not always be the case. In some cases you might want to use --save-dev or even --save-optional, so it wouldn't make sense to use npmrc.

package.json File

Within your package.json project file you can set parameters as well. In this case, the config map should be used, like this:

{
  "name": "module-name",
  "version": "10.3.1",
  "config": {
    "foo": "bar",
    "test-param": 12
  },
  "dependencies": {
    "express": "4.2.x",
  }
}

Then from within your code you can access these parameters using the process global variable, like this: process.env.npm_package_config_foo. Notice the prefix npm_package_config_, which tells Node where to get the variable from.

Note: This will only work when you run your project through an npm script (i.e., not just using node index.js).

npm config set

And lastly, there is always the ability to set parameters via npm config set. This will take precedence over the package.json configurations. So, for example, if you ran npm config set module-name:foo baz from the command line (and had the package.json file from above), then your foo parameter would be baz instead of bar. The module-name scoping will ensure that this variable is not set for any other projects.

Like the method above, for this to work you must run the program via an npm script, like npm run.

List of Possible Parameters

I tried to categorize each parameter as best as possible, but many of them would work well in other categories too. So, after some contemplating, I just put each param in the category that made the most sense for the context.

Hopefully I did well enough organizing this so that you can use it as a go-to reference. Feel free to let me know if there are any mistakes or omissions!

Access Control/Authorization

access

This sets the scope access level of a package, which defaults to restricted. Setting this parameter to public makes it publicly viewable and installable. If your project is unscoped, then it is public.

• Default: restricted
• Type: Access (string)

always-auth

Set to true if you want to require authentication for every time you access the registry, even for GET requests.

• Default: false
• Type: Boolean

ca

This is the Certificate Authority signing certificate that is used for trusting an SSL connection with the package registry. To specify the certificate, use the PEM format and replace all newlines with the \n character. So, for example, setting the CA might look like:

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

You can also trust multiple CAs by specifying an array of certificates, one for each line:

ca[]="..."
ca[]="..."

Or, setting ca to null will specify the default known registrars.

• Default: The npm CA certificate
• Type: String, Array or null

cafile

Similar to the ca parameter, cafile allows you to set the trusted certificate for connecting to the registry. The difference here is that you can specify a file path to the certificate, which can contain one or multiple certificates.

• Default: null
• Type: path

cert

The cert parameter specifies the client certificate for authenticating with a registry. This is opposed to the previous ca and cafile certificates in that it is for client authentication instead of registry authentication. If you host your own registry, this could be a good way to make it private without having to authenticate with a username and password.

• Default: null
• Type: String

Caching

cache

This is the location of npm's cache directory.

• Default: Windows: %AppData%\npm-cache, Posix: ~/.npm
• Type: path

cache-lock-stale

The number of milliseconds before the cache folder lock files are considered stale.

• Default: 60000 (1 minute)
• Type: Number

cache-lock-retries

Number of times to retry to acquire a lock on cache folder lock files.

• Default: 10
• Type: Number

cache-lock-wait

Number of milliseconds to wait for cache lock files to expire.

• Default: 10000 (10 seconds)
• Type: Number

cache-max

This is the maximum time (in seconds) in which an item is cached before updating with the registry. So if you anticipate a package to change fairly often, then you'll want to set this to a lower number.

The only time cached packages are purged is when the npm cache clean command is used (or, alternatively, you can manually clean out packages to pick and choose which are purged).

• Default: Infinity
• Type: Number

cache-min

Opposite of the cache-max parameter, the cache-min parameter sets the minimum time (in seconds) to keep items in the cache before checking against the registry again.

• Default: 10
• Type: Number

General

color

The color param determines if coloring is used in the npm output. If set to true, then npm only prints colors for tty file descriptors. Or you can set it to always to always use colors.

• Default: true on Posix, false on Windows
• Type: Boolean or "always"

description

Determines if the package description is shown when using npm search.

• Default: true
• Type: Boolean

force

Using force will make the various commands more forceful. You can almost think of it as using sudo, where you'll be able to bypass certain restrictions. So, to name a few examples, using this would mean a lifecycle script failure does not block progress, publishing overwrites previously published versions, npm skips the cache when requesting from the registry, or it would prevent checks against overwriting non-npm files.

• Default: false
• Type: Boolean

global

global causes a given command to operate in the 'global' mode. Packages installed in this folder can be accessed by all users and projects on the system. This means that packages are installed into the 'prefix' folder, which is typically where node is installed. Specifically, the global packages will be located at {prefix}/lib/node_modules, bin files will be linked to {prefix}/bin, and man pages are would be linked to {prefix}/share/man.

• Default: false
• Type: Boolean

globalconfig

The location of the config file to read for global configuration options.

• Default: {prefix}/etc/npmrc
• Type: path

group

This parameter tells npm which system group to use when running package scripts in global mode as the root user.

• Default: the group ID of the current process
• Type: String or Number

long

Whether or not to show detailed information when running npm ls and npm search.

• Default: false
• Type: Boolean

prefix

This is the location where global items are installed, which by default is the install location of npm itself. If prefix is set on the command line, then non-global commands are forced to run in the given folder.

• Default: see npm help 5 folders
• Type: path

spin

The spin parameter determines whether or not an ASCII spinner is displayed while npm is waiting or processing something (assuming process.stderr is a TTY). This can be set to false to suppress the spinner completely, or set to 'always' to output the spinner even for non-TTY outputs.

• Default: true
• Type: Boolean or "always"

tmp

The directory where temporary files and directories are stored. Once the npm process has completed successfully, all of the files and directories are deleted. If the process fails, however, the files and directories are not deleted so you can inspect them and debug the problem.

• Default: TMPDIR environment variable, or "/tmp"
• Type: path

Unicode

The unicode parameter tells npm whether or not to use Unicode characters in the tree output. If false, only ASCII characters are used to draw the trees.

• Default: true
• Type: Boolean

unsafe-perm

When unsafe-perm is set to true, the user/group ID switching is suppressed when a package script is run. If false, non-root users will not be able to install packages.

• Default: false if running as root, true otherwise
• Type: Boolean

usage

Using the usage flag reduces the amount of output when getting help for a command. Instead of showing you every possible flag/input to a command, like the -H flag would, it just gives you the gist of the help documentation. So, for example, executing npm --usage search would output npm search [some search terms ...].

• Default: false
• Type: Boolean

user

This is the UID to use when a package script is run as root. So if you don't want the script to have root permissions, set this to the UID of the user that has the correct permission level and access for the application. Running a package script as root can be dangerous!

• Default: "nobody"
• Type: String or Number

userconfig

This is the location of a user-level configuration file. Each user on a system can have different settings for the npm install, and the file should be located at the path given in userconfig.

• Default: ~/.npmrc
• Type: path

umask

This is the mask value to use when setting the file creation mode for both files and directories. The type of file/directory being created depends on the mask value used. If it is a directory or an executable, then the umask value is masked against 0777. For all other files, the umask value is masked against 0666. The defaults are 0755 and 0644 respectively, which is a fairly conservative mask for each file type.

• Default: 022
• Type: Octal numeric string in range 0000..0777 (0..511)

version

Using this flag outputs the version of npm installed. This only works when used on the command line as a flag like npm --version.

• Default: false
• Type: boolean

versions

Using this flag is similar to version, but it outputs version detail (as JSON) on a few different packages, including the project in the current directory (if present), V8, npm, and details from process.versions. This only works when used on the command line as a flag like npm --versions.

An example output might look like:

{ 'my-project': '0.0.1',
  npm: '2.14.2',
  http_parser: '2.3',
  modules: '14',
  node: '0.12.2',
  openssl: '1.0.1m',
  uv: '1.4.2-node1',
  v8: '3.28.73',
  zlib: '1.2.8' }

• Default: false
• Type: boolean

viewer

This is the program to be used when viewing help content. If set to browser, the default web browser will open and show the help content in HTML.

• Default: man on Posix, browser on Windows
• Type: path, man, or browser

Development

dev

Using this flag when installing packages will also install the dev-dependencies packages as well. This should almost always be used when not running a project in production.

This is similar to the npat flag.

• Default: false
• Type: Boolean

editor

This is the command (or path to an executable) to be run when opening an editor.

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

engine-strict

This parameter tells npm if it should follow the engine specification in a package.json file strictly. If set to true, then a package installation will fail if the current Node.js version does not match the one specified.

This is useful for when a package requires a certain Node.js version, or even io.js (possibly because the package uses ES6 features).

• Default: false
• Type: Boolean

git

This should be the command to use for running git commands. This could be useful for when git is installed, but it isn't on the PATH, in which case you'd specify the path of the git install.

• Default: "git"
• Type: String

git-tag-version

This tells npm if it should tag the commit when running the npm version command (which bumps the package version and saves it to package.json). This may help reduce mistakes (forgetting to tag the git commit, tagging it as the wrong version, etc), but it also gives you less control, so you'll have to weigh the trade-offs.

• Default: true
• Type: Boolean

heading

The string to be printed when outputting debug information.

• Default: "npm"
• Type: String

if-present

When using the npm run-script command, if the script is not defined in the package.json file, then npm exits with an error code. If if-present is set to true, then the error code is not returned. This is useful for when you optionally want to run a script, but don't care if it is not present. So, for example, maybe you have a script (script A) that is present in some of your projects, but not all, and you use another generic script (script B) to run it. This way if script A isn't present, then script B won't get an error and can safely keep executing.

• Default: false
• Type: Boolean

ignore-scripts

Set this flag to not run any scripts defined in the package.json file of a project.

• Default: false
• Type: Boolean

init-module

This is the path to a JavaScript file that helps with initializing a project. So if you have a custom configuration that you want all of your new projects to have (like maybe a dependency on Bluebird or a default engine), then you can create a file in the location specified to handle the initialization for you.

• Default: ~/.npm-init.js
• Type: path

init-author-name

The default name used by npm init when creating a new project.

• Default: ""
• Type: String

init-author-email

The default author email used by npm init when creating a new project.

• Default: ""
• Type: String

init-author-url

The default author URL used by npm init when creating a new project.

• Default: ""
• Type: String

init-license

The default license used by npm init when creating a new project.

• Default: "ISC"
• Type: String

init-version

The default version used by npm init when creating a new project.

• Default: "1.0.0"
• Type: String

JSON

This parameter determines whether or not npm writes its output as JSON or regular text.

NOTE: npm claims that this feature is experimental and the structure of the JSON objects is subject to change.

• Default: false
• Type: Boolean

link

If link is set to true, then the local installs will be linked to the global package installs (if a matching package is present). One important by-product of these features is that by linking to global packages, local installs can then cause other things to be installed in the global space.

Links are created if at least one of the two conditions are met:

• The package is not already installed globally

• the globally installed version is identical to the version that is being installed locally

• Default: false

• Type: Boolean

local-address

This is the IP address of the system's local networking interface to be used when connecting to the npm registry.

NOTE: This must be an IPv4 address in Node v0.12 and earlier.

• Default: undefined
• Type: IP Address

loglevel

This is the default log level for when running your application. If there is a log event higher (or equal to) than the one given here, then it is output to the user. When/if the application fails, all logs are written to npm-debug.log in the current working directory.

• Default: "warn"
• Type: String

logstream

The stream used by the npmlog package at runtime.

NOTE: This cannot be set on the command line. You must use another method, like a file or environment variable to configure it.

• Default: process.stderr
• Type: Stream

message

This is the commit message to be used by the npm version command. The '%s' formatting character will be replaced by the version number.

• Default: "%s"
• Type: String

node-version

The Node version is used when checking a package's engines declaration in the package.json file.

• Default: process.version
• Type: semver or false

npat

Whether or not to run a package's tests on installation.

• Default: false
• Type: Boolean

onload-script

This is the location of a package to require() once npm loads. This is recommended for programmatic usage of npm.

• Default: false
• Type: path, or 'false'

optional

This tells npm to install the packages from the optionalDependencies map in the package.json file. Since these are optional dependencies, if one fails to install then npm will not abort the process.

• Default: true
• Type: Boolean

parseable

The parseable parameter tells npm to format its output into a parse-able format when writing to standard output.

• Default: false
• Type: Boolean

production

When set to true, npm runs in production mode, which mostly just means devDependencies are not installed. Note that you should use NODE_ENV="production" environment variable instead when using lifecycle scripts.

• Default: false
• Type: Boolean

rollback

Using this flag with npm will remove any packages that failed to install (maybe due to compilation/dependency error, for example).

• Default: true
• Type: Boolean

save

Using this flag with npm saves the given package to the local package.json file under dependencies. Alternatively, using this flag with the npm rm command will remove a dependency from the dependencies section of the package.json file.

Note that this only works when a package.json file is present in the current directory.

• Default: false
• Type: Boolean

save-bundle

If a package is saved at install time by using the --save, --save-dev, or --save-optional flags, then also put it in the bundleDependencies list. When used with the npm rm command, it removes it from the bundledDependencies list.

• Default: false
• Type: Boolean

save-dev

Using this flag saves packages to the devDependencies list in the package.json file. The opposite is true when used with npm rm, meaning the package will be removed from devDependencies. Like the save flag, this only works if there is a package.json file present.

• Default: false
• Type: Boolean

save-exact

When a dependency is saved to the package.json file using one of the --save, --save-dev or --save-optional flags, then it will be configured using the exact version number instead of npm's default semver range operator.

• Default: false
• Type: Boolean

save-optional

Using this flag saves packages to the optionalDependencies list in the package.json file. The opposite is true when used with npm rm, meaning the package will be removed from optionalDependencies. Like the save flag, this only works if there is a package.json file present.

• Default: false
• Type: Boolean

save-prefix

This parameter determines how packages are saved to package.json if used with the --save or --save-dev flags. Using the default value as an example, if we save a package with the version 1.2.3, then it will actually be saved in package.json as ^1.2.3.

• Default: '^'
• Type: String

scope

Using scope tells npm what scope to use for a scoped registry. This could be useful when using a private registry for the first time. Example:

npm login --scope=@organization --registry=registry.example.com

This causes @organization to be mapped to this registry for future installations of packages specified according to the pattern @organization/package.

• Default: ""
• Type: String

shrinkwrap

When false, the npm-shrinkwrap.json file is ignored during installation.

• Default: true
• Type: Boolean

sign-git-tag

When executing the npm version command and using this flag, the -s flag will be used during tagging to add a signature. In order for this to work, you must have already set up GPG keys in your git configs.

• Default: false
• Type: Boolean

tag

When installing a package from npm and not specifying the version, this tag will be used instead.

• Default: latest
• Type: String

tag-version-prefix

This is the character prepended to the package version when using the npmversion. This is useful for when other programs have a styling convention for versions.

• Default: "v"
• Type: String

Networking

https-proxy

The proxy used for outgoing HTTPS connections. If any of the following environment variables are set, then they are used instead: HTTPS_PROXY, https_proxy, HTTP_PROXY, http_proxy.

• Default: null
• Type: URL

proxy

The proxy used for outgoing HTTP connections. If any of the following environment variables are set, then they are used instead: HTTP_PROXY, http_proxy.

• Default: null
• Type: URL

strict-ssl

This tells npm whether or not to use SSL for connecting with the registry via HTTPS.

• Default: true
• Type: Boolean

user-agent

Sets the User-Agent request header for HTTP(S) requests.

• Default: node/{process.version} {process.platform} {process.arch}
• Type: String

Registry

fetch-retries

The number of times npm tries to contact the registry to fetch a package.

• Default: 2
• Type: Number

fetch-retry-factor

The "factor" config for the retry module to use when fetching packages.

• Default: 10
• Type: Number

fetch-retry-mintimeout

The minimum time to wait before timing out when fetching packages from the registry.

• Default: 10000 (10 seconds)
• Type: Number (milliseconds)

fetch-retry-maxtimeout

The maximum time to wait before timing out when fetching packages from the registry.

• Default: 10000 (10 seconds)
• Type: Number (milliseconds)

key

This is the client key to use when authenticating with the registry.

• Default: null
• Type: String

registry

The URL of the registry to use for fetching and publishing packages.

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

searchopts

A space-separated list of options that are always used for searching the registry.

• Default: ""
• Type: String

searchexclude

A space-separated list of limits that are always used for searching the registry.

• Default: ""
• Type: String

searchsort

This indicates which field in the results should be sorted on. To reverse the sorting order, just prefix it with a -.

• Default: "name"
• Type: String
• Values: "name", "-name", "date", "-date", "description", "-description", "keywords", "-keywords"