{"id":15290311,"url":"https://github.com/npm/config","last_synced_at":"2025-10-07T03:32:56.665Z","repository":{"id":40517983,"uuid":"286825745","full_name":"npm/config","owner":"npm","description":"Configuration management for https://github.com/npm/cli","archived":true,"fork":false,"pushed_at":"2022-11-02T18:04:58.000Z","size":411,"stargazers_count":32,"open_issues_count":0,"forks_count":18,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-10-01T16:07:07.449Z","etag":null,"topics":["npm-cli"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null}},"created_at":"2020-08-11T19:01:25.000Z","updated_at":"2023-08-25T22:33:28.000Z","dependencies_parsed_at":"2022-07-26T12:17:31.047Z","dependency_job_id":null,"html_url":"https://github.com/npm/config","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npm","download_url":"https://codeload.github.com/npm/config/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235586087,"owners_count":19014028,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["npm-cli"],"created_at":"2024-09-30T16:06:57.602Z","updated_at":"2025-10-07T03:32:51.368Z","avatar_url":"https://github.com/npm.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## NOTICE\n\nThe code for this module is now maintained inside a workspace of the npm cli itself:\n\nhttps://github.com/npm/cli/blob/HEAD/workspaces/config\n\n# `@npmcli/config`\n\nConfiguration management for the npm cli.\n\nThis module is the spiritual descendant of\n[`npmconf`](http://npm.im/npmconf), and the code that once lived in npm's\n`lib/config/` folder.\n\nIt does the management of configuration files that npm uses, but\nimportantly, does _not_ define all the configuration defaults or types, as\nthose parts make more sense to live within the npm CLI itself.\n\nThe only exceptions:\n\n- The `prefix` config value has some special semantics, setting the local\n  prefix if specified on the CLI options and not in global mode, or the\n  global prefix otherwise.\n- The `project` config file is loaded based on the local prefix (which can\n  only be set by the CLI config options, and otherwise defaults to a walk\n  up the folder tree to the first parent containing a `node_modules`\n  folder, `package.json` file, or `package-lock.json` file.)\n- The `userconfig` value, as set by the environment and CLI (defaulting to\n  `~/.npmrc`, is used to load user configs.\n- The `globalconfig` value, as set by the environment, CLI, and\n  `userconfig` file (defaulting to `$PREFIX/etc/npmrc`) is used to load\n  global configs.\n- A `builtin` config, read from a `npmrc` file in the root of the npm\n  project itself, overrides all defaults.\n\nThe resulting hierarchy of configs:\n\n- CLI switches.  eg `--some-key=some-value` on the command line.  These are\n  parsed by [`nopt`](http://npm.im/nopt), which is not a great choice, but\n  it's the one that npm has used forever, and changing it will be\n  difficult.\n- Environment variables.  eg `npm_config_some_key=some_value` in the\n  environment.  There is no way at this time to modify this prefix.\n- INI-formatted project configs.  eg `some-key = some-value` in the\n  `localPrefix` folder (ie, the `cwd`, or its nearest parent that contains\n  either a `node_modules` folder or `package.json` file.)\n- INI-formatted userconfig file.  eg `some-key = some-value` in `~/.npmrc`.\n  The `userconfig` config value can be overridden by the `cli`, `env`, or\n  `project` configs to change this value.\n- INI-formatted globalconfig file.  eg `some-key = some-value` in\n  the `globalPrefix` folder, which is inferred by looking at the location\n  of the node executable, or the `prefix` setting in the `cli`, `env`,\n  `project`, or `userconfig`.  The `globalconfig` value at any of those\n  levels can override this.\n- INI-formatted builtin config file.  eg `some-key = some-value` in\n  `/usr/local/lib/node_modules/npm/npmrc`.  This is not configurable, and\n  is determined by looking in the `npmPath` folder.\n- Default values (passed in by npm when it loads this module).\n\n## USAGE\n\n```js\nconst Config = require('@npmcli/config')\n// the types of all the configs we know about\nconst types = require('./config/types.js')\n// default values for all the configs we know about\nconst defaults = require('./config/defaults.js')\n// if you want -c to be short for --call and so on, define it here\nconst shorthands = require('./config/shorthands.js')\n\nconst conf = new Config({\n  // path to the npm module being run\n  npmPath: resolve(__dirname, '..'),\n  types,\n  shorthands,\n  defaults,\n  // optional, defaults to process.argv\n  argv: process.argv,\n  // optional, defaults to process.env\n  env: process.env,\n  // optional, defaults to process.execPath\n  execPath: process.execPath,\n  // optional, defaults to process.platform\n  platform: process.platform,\n  // optional, defaults to process.cwd()\n  cwd: process.cwd(),\n})\n\n// emits log events on the process object\n// see `proc-log` for more info\nprocess.on('log', (level, ...args) =\u003e {\n  console.log(level, ...args)\n})\n\n// returns a promise that fails if config loading fails, and\n// resolves when the config object is ready for action\nconf.load().then(() =\u003e {\n  conf.validate()\n  console.log('loaded ok! some-key = ' + conf.get('some-key'))\n}).catch(er =\u003e {\n  console.error('error loading configs!', er)\n})\n```\n\n## API\n\nThe `Config` class is the sole export.\n\n```js\nconst Config = require('@npmcli/config')\n```\n\n### static `Config.typeDefs`\n\nThe type definitions passed to `nopt` for CLI option parsing and known\nconfiguration validation.\n\n### constructor `new Config(options)`\n\nOptions:\n\n- `types` Types of all known config values.  Note that some are effectively\n  given semantic value in the config loading process itself.\n- `shorthands` An object mapping a shorthand value to an array of CLI\n  arguments that replace it.\n- `defaults` Default values for each of the known configuration keys.\n  These should be defined for all configs given a type, and must be valid.\n- `npmPath` The path to the `npm` module, for loading the `builtin` config\n  file.\n- `cwd` Optional, defaults to `process.cwd()`, used for inferring the\n  `localPrefix` and loading the `project` config.\n- `platform` Optional, defaults to `process.platform`.  Used when inferring\n  the `globalPrefix` from the `execPath`, since this is done diferently on\n  Windows.\n- `execPath` Optional, defaults to `process.execPath`.  Used to infer the\n  `globalPrefix`.\n- `env` Optional, defaults to `process.env`.  Source of the environment\n  variables for configuration.\n- `argv` Optional, defaults to `process.argv`.  Source of the CLI options\n  used for configuration.\n\nReturns a `config` object, which is not yet loaded.\n\nFields:\n\n- `config.globalPrefix` The prefix for `global` operations.  Set by the\n  `prefix` config value, or defaults based on the location of the\n  `execPath` option.\n- `config.localPrefix` The prefix for `local` operations.  Set by the\n  `prefix` config value on the CLI only, or defaults to either the `cwd` or\n  its nearest ancestor containing a `node_modules` folder or `package.json`\n  file.\n- `config.sources` A read-only `Map` of the file (or a comment, if no file\n  found, or relevant) to the config level loaded from that source.\n- `config.data` A `Map` of config level to `ConfigData` objects.  These\n  objects should not be modified directly under any circumstances.\n  - `source` The source where this data was loaded from.\n  - `raw` The raw data used to generate this config data, as it was parsed\n    initially from the environment, config file, or CLI options.\n  - `data` The data object reflecting the inheritance of configs up to this\n    point in the chain.\n  - `loadError` Any errors encountered that prevented the loading of this\n    config data.\n- `config.list` A list sorted in priority of all the config data objects in\n  the prototype chain.  `config.list[0]` is the `cli` level,\n  `config.list[1]` is the `env` level, and so on.\n- `cwd` The `cwd` param\n- `env` The `env` param\n- `argv` The `argv` param\n- `execPath` The `execPath` param\n- `platform` The `platform` param\n- `defaults` The `defaults` param\n- `shorthands` The `shorthands` param\n- `types` The `types` param\n- `npmPath` The `npmPath` param\n- `globalPrefix` The effective `globalPrefix`\n- `localPrefix` The effective `localPrefix`\n- `prefix` If `config.get('global')` is true, then `globalPrefix`,\n  otherwise `localPrefix`\n- `home` The user's home directory, found by looking at `env.HOME` or\n  calling `os.homedir()`.\n- `loaded` A boolean indicating whether or not configs are loaded\n- `valid` A getter that returns `true` if all the config objects are valid.\n  Any data objects that have been modified with `config.set(...)` will be\n  re-evaluated when `config.valid` is read.\n\n### `config.load()`\n\nLoad configuration from the various sources of information.\n\nReturns a `Promise` that resolves when configuration is loaded, and fails\nif a fatal error is encountered.\n\n### `config.find(key)`\n\nFind the effective place in the configuration levels a given key is set.\nReturns one of: `cli`, `env`, `project`, `user`, `global`, `builtin`, or\n`default`.\n\nReturns `null` if the key is not set.\n\n### `config.get(key, where = 'cli')`\n\nLoad the given key from the config stack.\n\n### `config.set(key, value, where = 'cli')`\n\nSet the key to the specified value, at the specified level in the config\nstack.\n\n### `config.delete(key, where = 'cli')`\n\nDelete the configuration key from the specified level in the config stack.\n\n### `config.validate(where)`\n\nVerify that all known configuration options are set to valid values, and\nlog a warning if they are invalid.\n\nInvalid auth options will cause this method to throw an error with a `code`\nproperty of `ERR_INVALID_AUTH`, and a `problems` property listing the specific\nconcerns with the current configuration.\n\nIf `where` is not set, then all config objects are validated.\n\nReturns `true` if all configs are valid.\n\nNote that it's usually enough (and more efficient) to just check\n`config.valid`, since each data object is marked for re-evaluation on every\n`config.set()` operation.\n\n### `config.repair(problems)`\n\nAccept an optional array of problems (as thrown by `config.validate()`) and\nperform the necessary steps to resolve them. If no problems are provided,\nthis method will call `config.validate()` internally to retrieve them.\n\nNote that you must `await config.save('user')` in order to persist the changes.\n\n### `config.isDefault(key)`\n\nReturns `true` if the value is coming directly from the\ndefault definitions, if the current value for the key config is\ncoming from any other source, returns `false`.\n\nThis method can be used for avoiding or tweaking default values, e.g:\n\n\u003e  Given a global default definition of foo='foo' it's possible to read that\n\u003e  value such as:\n\u003e\n\u003e  ```js\n\u003e     const save = config.get('foo')\n\u003e  ```\n\u003e\n\u003e  Now in a different place of your app it's possible to avoid using the `foo`\n\u003e  default value, by checking to see if the current config value is currently\n\u003e  one that was defined by the default definitions:\n\u003e\n\u003e  ```js\n\u003e     const save = config.isDefault('foo') ? 'bar' : config.get('foo')\n\u003e  ```\n\n### `config.save(where)`\n\nSave the config file specified by the `where` param.  Must be one of\n`project`, `user`, `global`, `builtin`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Fconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpm%2Fconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Fconfig/lists"}