npm@npmcli/config
Configuration management for the npm cli.
This module is the spiritual descendant of
npmconf, and the code that once lived in npm's
lib/config/ folder.
It does the management of configuration files that npm uses, but importantly, does not define all the configuration defaults or types, as those parts make more sense to live within the npm CLI itself.
The only exceptions:
- The
prefixconfig value has some special semantics, setting the local prefix if specified on the CLI options and not in global mode, or the global prefix otherwise. - The
projectconfig file is loaded based on the local prefix (which can only be set by the CLI config options, and otherwise defaults to a walk up the folder tree to the first parent containing anode_modulesfolder,package.jsonfile, orpackage-lock.jsonfile.) - The
userconfigvalue, as set by the environment and CLI (defaulting to~/.npmrc, is used to load user configs. - The
globalconfigvalue, as set by the environment, CLI, anduserconfigfile (defaulting to$PREFIX/etc/npmrc) is used to load global configs. - A
builtinconfig, read from anpmrcfile in the root of the npm project itself, overrides all defaults.
The resulting hierarchy of configs:
- CLI switches. eg
--some-key=some-valueon the command line. These are parsed bynopt, which is not a great choice, but it's the one that npm has used forever, and changing it will be difficult. - Environment variables. eg
npm_config_some_key=some_valuein the environment. There is no way at this time to modify this prefix. - INI-formatted project configs. eg
some-key = some-valuein thelocalPrefixfolder (ie, thecwd, or its nearest parent that contains either anode_modulesfolder orpackage.jsonfile.) - INI-formatted userconfig file. eg
some-key = some-valuein~/.npmrc. Theuserconfigconfig value can be overridden by thecli,env, orprojectconfigs to change this value. - INI-formatted globalconfig file. eg
some-key = some-valuein theglobalPrefixfolder, which is inferred by looking at the location of the node executable, or theprefixsetting in thecli,env,project, oruserconfig. Theglobalconfigvalue at any of those levels can override this. - INI-formatted builtin config file. eg
some-key = some-valuein/usr/local/lib/node_modules/npm/npmrc. This is not configurable, and is determined by looking in thenpmPathfolder. - Default values (passed in by npm when it loads this module).
USAGE
const Config = require('@npmcli/config')
const { shorthands, definitions, flatten } = require('@npmcli/config/lib/definitions')
const conf = new Config({
// path to the npm module being run
npmPath: resolve(__dirname, '..'),
definitions,
shorthands,
flatten,
// optional, defaults to process.argv
// argv: [] <- if you are using this package in your own cli
// and dont want to have colliding argv
argv: process.argv,
// optional, defaults to process.env
env: process.env,
// optional, defaults to process.execPath
execPath: process.execPath,
// optional, defaults to process.platform
platform: process.platform,
// optional, defaults to process.cwd()
cwd: process.cwd(),
})
// emits log events on the process object
// see `proc-log` for more info
process.on('log', (level, ...args) => {
console.log(level, ...args)
})
// returns a promise that fails if config loading fails, and
// resolves when the config object is ready for action
conf.load().then(() => {
conf.validate()
console.log('loaded ok! some-key = ' + conf.get('some-key'))
}).catch(er => {
console.error('error loading configs!', er)
})API
The Config class is the sole export.
const Config = require('@npmcli/config')static Config.typeDefs
The type definitions passed to nopt for CLI option parsing and known
configuration validation.
constructor new Config(options)
Options:
typesTypes of all known config values. Note that some are effectively given semantic value in the config loading process itself.shorthandsAn object mapping a shorthand value to an array of CLI arguments that replace it.defaultsDefault values for each of the known configuration keys. These should be defined for all configs given a type, and must be valid.npmPathThe path to thenpmmodule, for loading thebuiltinconfig file.cwdOptional, defaults toprocess.cwd(), used for inferring thelocalPrefixand loading theprojectconfig.platformOptional, defaults toprocess.platform. Used when inferring theglobalPrefixfrom theexecPath, since this is done diferently on Windows.execPathOptional, defaults toprocess.execPath. Used to infer theglobalPrefix.envOptional, defaults toprocess.env. Source of the environment variables for configuration.argvOptional, defaults toprocess.argv. Source of the CLI options used for configuration.
Returns a config object, which is not yet loaded.
Fields:
config.globalPrefixThe prefix forglobaloperations. Set by theprefixconfig value, or defaults based on the location of theexecPathoption.config.localPrefixThe prefix forlocaloperations. Set by theprefixconfig value on the CLI only, or defaults to either thecwdor its nearest ancestor containing anode_modulesfolder orpackage.jsonfile.config.sourcesA read-onlyMapof the file (or a comment, if no file found, or relevant) to the config level loaded from that source.config.dataAMapof config level toConfigDataobjects. These objects should not be modified directly under any circumstances.sourceThe source where this data was loaded from.rawThe raw data used to generate this config data, as it was parsed initially from the environment, config file, or CLI options.dataThe data object reflecting the inheritance of configs up to this point in the chain.loadErrorAny errors encountered that prevented the loading of this config data.
config.listA list sorted in priority of all the config data objects in the prototype chain.config.list[0]is theclilevel,config.list[1]is theenvlevel, and so on.cwdThecwdparamenvTheenvparamargvTheargvparamexecPathTheexecPathparamplatformTheplatformparamdefaultsThedefaultsparamshorthandsTheshorthandsparamtypesThetypesparamnpmPathThenpmPathparamglobalPrefixThe effectiveglobalPrefixlocalPrefixThe effectivelocalPrefixprefixIfconfig.get('global')is true, thenglobalPrefix, otherwiselocalPrefixhomeThe user's home directory, found by looking atenv.HOMEor callingos.homedir().loadedA boolean indicating whether or not configs are loadedvalidA getter that returnstrueif all the config objects are valid. Any data objects that have been modified withconfig.set(...)will be re-evaluated whenconfig.validis read.
config.load()
Load configuration from the various sources of information.
Returns a Promise that resolves when configuration is loaded, and fails
if a fatal error is encountered.
config.find(key)
Find the effective place in the configuration levels a given key is set.
Returns one of: cli, env, project, user, global, builtin, or
default.
Returns null if the key is not set.
config.get(key, where = 'cli')
Load the given key from the config stack.
config.set(key, value, where = 'cli')
Set the key to the specified value, at the specified level in the config stack.
config.delete(key, where = 'cli')
Delete the configuration key from the specified level in the config stack.
config.validate(where)
Verify that all known configuration options are set to valid values, and log a warning if they are invalid.
Invalid auth options will cause this method to throw an error with a code
property of ERR_INVALID_AUTH, and a problems property listing the specific
concerns with the current configuration.
If where is not set, then all config objects are validated.
Returns true if all configs are valid.
Note that it's usually enough (and more efficient) to just check
config.valid, since each data object is marked for re-evaluation on every
config.set() operation.
config.repair(problems)
Accept an optional array of problems (as thrown by config.validate()) and
perform the necessary steps to resolve them. If no problems are provided,
this method will call config.validate() internally to retrieve them.
Note that you must await config.save('user') in order to persist the changes.
config.isDefault(key)
Returns true if the value is coming directly from the
default definitions, if the current value for the key config is
coming from any other source, returns false.
This method can be used for avoiding or tweaking default values, e.g:
Given a global default definition of foo='foo' it's possible to read that value such as:
const save = config.get('foo')Now in a different place of your app it's possible to avoid using the
foodefault value, by checking to see if the current config value is currently one that was defined by the default definitions:const save = config.isDefault('foo') ? 'bar' : config.get('foo')
config.save(where)
Save the config file specified by the where param. Must be one of
project, user, global, builtin.