Managing npm Configuration Files with npmrc

Last update on July 16 2024 13:05:09 (UTC/GMT +8 hours)

In the last tutorial we showed you how npm configures the files obtained during npm install and where they are stored. This tutorial will give you an overview of the npm config files.

The npmrc manages the npm config files.

Description

The config setting for npm is gotten from the command line, environment variables and the npmrc files.

You can use the npm config command to update and edit the contents of the user and global npmrc files.

FILES

Npmrc has four relevant files, they are:

The per-project config file (/path/to/my/project/.npmrc)
The per-user config file (~/.npmrc)
The global config file ($PREFIX/etc/npmrc)
The npm builtin config file (/path/to/npm/npmrc)

All the npm config files are an ini-formatted list of key = value parameters. The environment variables can be replaced with the use of ${VARIABLE_NAME}. For instance:

prefix = ${HOME}/.npm-packages

Each of these files will be loaded, and the config options will be resolved in priority order. For example, a setting in the userconfig will override the setting in the globalconfig. If you want to specify array values, you do so by adding "[]" after the key name. Here is an example:

key[] = "first value"
key[] = "second value"

comments

All lines in .npmrc files are interpreted as comments when they begin with a ; or a # character. .npmrc are usually parsed by npm/ini, which will specify this comment syntax.

An example is shown below:

# last modified: 01 Jan 2016
;Sets a new registry for a scoped package
@myscope:registry=https://mycustomregistry.example.org

Per-project config file

Whenever you are working locally in a project, the config values for that specific project is set by a .npmrc file in the root of the project(ie, a sibling of node_modules and the package.json).

It should be noted that this only applies to the root of the project that you are running npm in. it has no effect when you publish the module. For instance, you cannot publish a module that forces itself to install globally, or in another location.

In addition, this file cannot be read in global mode, such as when you are running npm install -g.

Per-user config file

$HOME/.npmrc (or the userconfig param, if it is set in the environment or on the command line)

Global config file

$PREFIX/etc/npmrc (or the globalconfig param, if it is set above): This file is an ini-file formatted list of key = value parameters. You can replace environment variables as shown above.

Built-in config file

path/to/npm/itself/npmrc

This file is an unchangeable "builtin" configuration file that npm keeps consistent across updates. You should set fields in here using the ./configure script that comes with npm. This is primarily used for distribution maintainers to override default configs in a standard and consistent manner.

Previous: Understanding npm Folder Structure for Local and Global Installs.
Next: Understanding package-lock.json in npm.