@npmcli/config

What is @npmcli/config?

@npmcli/config is a configuration management library for Node.js applications, particularly designed to handle npm's configuration needs. It allows you to load, manage, and manipulate configuration settings from various sources such as environment variables, command-line arguments, and configuration files.

What are @npmcli/config's main functionalities?

Loading Configuration

This feature allows you to load configuration settings from various sources. The `load` method initializes the configuration by reading from environment variables, command-line arguments, and configuration files.

const { Config } = require('@npmcli/config');
const config = new Config();
config.load().then(() => {
  console.log(config.get('someKey'));
});

Setting Configuration

This feature allows you to set configuration values programmatically. The `set` method is used to assign a value to a specific configuration key.

const { Config } = require('@npmcli/config');
const config = new Config();
config.set('someKey', 'someValue');
console.log(config.get('someKey'));

Saving Configuration

This feature allows you to save the current configuration state back to the configuration file. The `save` method writes the current configuration settings to the appropriate file.

const { Config } = require('@npmcli/config');
const config = new Config();
config.set('someKey', 'someValue');
config.save().then(() => {
  console.log('Configuration saved!');
});

Other packages similar to @npmcli/config

config

The `config` package is a popular configuration management library for Node.js applications. It allows you to define configuration settings for different deployment environments and load them easily. Compared to @npmcli/config, it is more general-purpose and not specifically tailored for npm's configuration needs.

dotenv

The `dotenv` package loads environment variables from a `.env` file into `process.env`. It is simpler and more lightweight compared to @npmcli/config, focusing solely on environment variable management rather than a comprehensive configuration management solution.

rc

The `rc` package is a non-opinionated configuration loader for Node.js. It supports loading configuration from various sources like environment variables, command-line arguments, and configuration files. It is similar to @npmcli/config but is more general-purpose and not specifically designed for npm.

README

@npmcli/config

Configuration management for the npm cli.

This module is the spiritual decendant 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 prefix config 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 project config 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 a node_modules folder, package.json file, or package-lock.json file.)
• The userconfig value, as set by the environment and CLI (defaulting to ~/.npmrc, is used to load user configs.
• The globalconfig value, as set by the environment, CLI, and userconfig file (defaulting to $PREFIX/etc/npmrc) is used to load global configs.
• A builtin config, read from a npmrc file in the root of the npm project itself, overrides all defaults.

The resulting heirarchy of configs:

• CLI switches. eg --some-key=some-value on the command line. These are parsed by nopt, 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_value in the environment. There is no way at this time to modify this prefix.
• INI-formatted project configs. eg some-key = some-value in the localPrefix folder (ie, the cwd, or its nearest parent that contains either a node_modules folder or package.json file.)
• INI-formatted userconfig file. eg some-key = some-value in ~/.npmrc. The userconfig config value can be overridden by the cli, env, or project configs to change this value.
• INI-formatted globalconfig file. eg some-key = some-value in the globalPrefix folder, which is inferred by looking at the location of the node executable, or the prefix setting in the cli, env, project, or userconfig. The globalconfig value at any of those levels can override this.
• INI-formatted builtin config file. eg some-key = some-value in /usr/local/lib/node_modules/npm/npmrc. This is not configurable, and is determined by looking in the npmPath folder.
• Default values (passed in by npm when it loads this module).

USAGE

const Config = require('@npmcli/config')
// the types of all the configs we know about
const types = require('./config/types.js')
// default values for all the configs we know about
const defaults = require('./config/defaults.js')
// if you want -c to be short for --call and so on, define it here
const shorthands = require('./config/shorthands.js')

const conf = new Config({
  // path to the npm module being run
  npmPath: resolve(__dirname, '..'),
  types,
  shorthands,
  defaults,
  // optional, defaults to process.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(),
  // optional, defaults to emitting 'log' events on process object
  // only silly, verbose, warn, and error are logged by this module
  log: require('npmlog')
})

// returns a promise that fails if config loading fails, and
// resolves when the config object is ready for action
conf.load().then(() => {
  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:

• types Types of all known config values. Note that some are effectively given semantic value in the config loading process itself.
• shorthands An object mapping a shorthand value to an array of CLI arguments that replace it.
• defaults Default values for each of the known configuration keys. These should be defined for all configs given a type, and must be valid.
• npmPath The path to the npm module, for loading the builtin config file.
• cwd Optional, defaults to process.cwd(), used for inferring the localPrefix and loading the project config.
• platform Optional, defaults to process.platform. Used when inferring the globalPrefix from the execPath, since this is done diferently on Windows.
• execPath Optional, defaults to process.execPath. Used to infer the globalPrefix.
• log Optional, the object used to log debug messages, warnings, and errors. Defaults to emitting on the process object.
• env Optional, defaults to process.env. Source of the environment variables for configuration.
• argv Optional, defaults to process.argv. Source of the CLI options used for configuration.

Returns a config object, which is not yet loaded.

Fields:

• config.globalPrefix The prefix for global operations. Set by the prefix config value, or defaults based on the location of the execPath option.
• config.localPrefix The prefix for local operations. Set by the prefix config value on the CLI only, or defaults to either the cwd or its nearest ancestor containing a node_modules folder or package.json file.
• config.sources A read-only Map of the file (or a comment, if no file found, or relevant) to the config level loaded from that source.
• config.data A Map of config level to ConfigData objects. These objects should not be modified directly under any circumstances.
  • source The source where this data was loaded from.
  • raw The raw data used to generate this config data, as it was parsed initially from the environment, config file, or CLI options.
  • data The data object reflecting the inheritance of configs up to this point in the chain.
  • loadError Any errors encountered that prevented the loading of this config data.
• config.list A list sorted in priority of all the config data objects in the prototype chain. config.list[0] is the cli level, config.list[1] is the env level, and so on.
• cwd The cwd param
• env The env param
• argv The argv param
• execPath The execPath param
• platform The platform param
• log The log param
• defaults The defaults param
• shorthands The shorthands param
• types The types param
• npmPath The npmPath param
• globalPrefix The effective globalPrefix
• localPrefix The effective localPrefix
• prefix If config.get('global') is true, then globalPrefix, otherwise localPrefix
• home The user's home directory, found by looking at env.HOME or calling os.homedir().
• loaded A boolean indicating whether or not configs are loaded

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()

Verify that all known configuration options are set to valid values.

config.save(where)

Save the config file specified by the where param. Must be one of project, user, global, builtin.