0
# @npmcli/config
1

2
Configuration management library for the npm command-line interface providing hierarchical layered configuration system with comprehensive validation, type coercion, and environment variable integration.
3

4
## Package Information
5

6
- **Package Name**: @npmcli/config
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @npmcli/config`
10

11
## Core Imports
12

13
```javascript
14
const { Config } = require('@npmcli/config');
15
```
16

17
For ES modules:
18

19
```javascript
20
import { Config } from '@npmcli/config';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const { Config } = require('@npmcli/config');
27

28
// Create a config instance
29
const config = new Config({
30
  definitions: {
31
    // Define configuration fields
32
    registry: {
33
      type: 'url',
34
      default: 'https://registry.npmjs.org/',
35
      description: 'npm registry URL'
36
    },
37
    loglevel: {
38
      type: String,
39
      default: 'notice',
40
      description: 'logging level'
41
    }
42
  },
43
  shorthands: {
44
    reg: ['--registry']
45
  },
46
  flatten: (obj) => obj,
47
  npmPath: process.cwd()
48
});
49

50
// Load configuration from all sources
51
await config.load();
52

53
// Get configuration values
54
const registry = config.get('registry');
55
const loglevel = config.get('loglevel');
56

57
// Set configuration values
58
config.set('loglevel', 'verbose', 'user');
59

60
// Save configuration
61
await config.save('user');
62
```
63

64
## Architecture
65

66
@npmcli/config implements a layered configuration system with seven distinct layers ordered by precedence:
67

68
1. **CLI** - Command line arguments (highest priority)
69
2. **Environment** - Environment variables with npm_config_ prefix
70
3. **Project** - Project-level .npmrc file
71
4. **User** - User-level .npmrc file (~/.npmrc)
72
5. **Global** - Global .npmrc file (PREFIX/etc/npmrc)
73
6. **Builtin** - Built-in npm configuration
74
7. **Default** - Default values (lowest priority)
75

76
The system provides comprehensive features including:
77

78
- **Type System**: Full validation and coercion using nopt-based type definitions
79
- **Credential Management**: Registry-specific authentication handling with nerf-dart scoping
80
- **Environment Integration**: Automatic environment variable setting and expansion
81
- **Workspace Support**: Project workspace detection and configuration
82
- **Deprecation Handling**: Support for deprecated configuration keys with warnings
83

84
## Capabilities
85

86
### Core Configuration Management
87

88
Primary Config class providing hierarchical configuration loading, validation, and manipulation with support for multiple configuration sources and comprehensive type system.
89

90
```javascript { .api }
91
class Config {
92
  constructor(options: ConfigOptions);
93
  
94
  // Core operations
95
  load(): Promise<void>;
96
  get(key: string, where?: string): any;
97
  set(key: string, value: any, where?: string): void;
98
  delete(key: string, where?: string): void;
99
  find(key: string): string | null;
100
  
101
  // Validation and repair
102
  validate(where?: string): boolean;
103
  repair(problems?: ValidationProblem[]): void;
104
  
105
  // File operations
106
  save(where: string): Promise<void>;
107
  
108
  // Properties
109
  loaded: boolean;
110
  valid: boolean;
111
  flat: object;
112
  list: ConfigData[];
113
  data: Map<string, ConfigData>;
114
}
115

116
interface ConfigOptions {
117
  definitions: Record<string, ConfigDefinition>;
118
  shorthands?: Record<string, string[]>;
119
  flatten?: (obj: any) => any;
120
  npmPath: string;
121
  env?: Record<string, string>;
122
  argv?: string[];
123
  platform?: string;
124
  execPath?: string;
125
  cwd?: string;
126
}
127

128
interface ConfigDefinition {
129
  type: any;
130
  default?: any;
131
  description?: string;
132
  deprecated?: string | boolean;
133
}
134
```
135

136
[Configuration Management](./config-management.md)
137

138
### Credential Management
139

140
Registry authentication and credential handling with URI-based scoping for secure access to npm registries and private repositories.
141

142
```javascript { .api }
143
// Credential management methods
144
getCredentialsByURI(uri: string): Credentials | null;
145
setCredentialsByURI(uri: string, credentials: Credentials): void;
146
clearCredentialsByURI(uri: string): void;
147

148
interface Credentials {
149
  token?: string;
150
  username?: string;
151
  password?: string;
152
  email?: string;
153
  auth?: string;
154
  certfile?: string;
155
  keyfile?: string;
156
}
157
```
158

159
[Credential Management](./credentials.md)
160

161
### Utility Functions
162

163
Supporting utility functions for field parsing, environment variable handling, type validation, and configuration processing.
164

165
```javascript { .api }
166
// Main utility exports
167
const { 
168
  parseField,
169
  envReplace, 
170
  nerfDart,
171
  setEnvs,
172
  typeDescription,
173
  Umask
174
} = require('@npmcli/config/lib/...');
175

176
// Type definitions
177
const typeDefs = Config.typeDefs;
178
```
179

180
[Utility Functions](./utilities.md)
181

182
### Error Handling
183

184
Configuration-specific error classes for handling invalid authentication and configuration validation failures.
185

186
```javascript { .api }
187
const { ErrInvalidAuth } = require('@npmcli/config/lib/errors');
188

189
class ErrInvalidAuth extends Error {
190
  constructor(message: string, registry: string);
191
  registry: string;
192
}
193
```
194

195
[Error Handling](./errors.md)
196

197
## Types
198

199
```javascript { .api }
200
// Configuration data structure
201
interface ConfigData {
202
  data: Record<string, any>;
203
  source: string;
204
}
205

206
// Validation problem reporting
207
interface ValidationProblem {
208
  path: string;
209
  message: string;
210
}
211

212
// Type definition structure
213
interface TypeDefinition {
214
  type: any;
215
  validate?: (data: any, key: string, value: any) => boolean;
216
  description?: string;
217
}
218
```