or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

config-management.mdcredentials.mderrors.mdindex.mdutilities.md
tile.json

tessl/npm-npmcli--config

Configuration management for the npm command-line interface with hierarchical layered configuration system.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@npmcli/config@6.0.x

To install, run

npx @tessl/cli install tessl/npm-npmcli--config@6.0.0

index.mddocs/

@npmcli/config

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

Package Information

  • Package Name: @npmcli/config
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install @npmcli/config

Core Imports

const { Config } = require('@npmcli/config');

For ES modules:

import { Config } from '@npmcli/config';

Basic Usage

const { Config } = require('@npmcli/config');

// Create a config instance
const config = new Config({
  definitions: {
    // Define configuration fields
    registry: {
      type: 'url',
      default: 'https://registry.npmjs.org/',
      description: 'npm registry URL'
    },
    loglevel: {
      type: String,
      default: 'notice',
      description: 'logging level'
    }
  },
  shorthands: {
    reg: ['--registry']
  },
  flatten: (obj) => obj,
  npmPath: process.cwd()
});

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

// Get configuration values
const registry = config.get('registry');
const loglevel = config.get('loglevel');

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

// Save configuration
await config.save('user');

Architecture

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

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

The system provides comprehensive features including:

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

Capabilities

Core Configuration Management

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

class Config {
  constructor(options: ConfigOptions);
  
  // Core operations
  load(): Promise<void>;
  get(key: string, where?: string): any;
  set(key: string, value: any, where?: string): void;
  delete(key: string, where?: string): void;
  find(key: string): string | null;
  
  // Validation and repair
  validate(where?: string): boolean;
  repair(problems?: ValidationProblem[]): void;
  
  // File operations
  save(where: string): Promise<void>;
  
  // Properties
  loaded: boolean;
  valid: boolean;
  flat: object;
  list: ConfigData[];
  data: Map<string, ConfigData>;
}

interface ConfigOptions {
  definitions: Record<string, ConfigDefinition>;
  shorthands?: Record<string, string[]>;
  flatten?: (obj: any) => any;
  npmPath: string;
  env?: Record<string, string>;
  argv?: string[];
  platform?: string;
  execPath?: string;
  cwd?: string;
}

interface ConfigDefinition {
  type: any;
  default?: any;
  description?: string;
  deprecated?: string | boolean;
}

Configuration Management

Credential Management

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

// Credential management methods
getCredentialsByURI(uri: string): Credentials | null;
setCredentialsByURI(uri: string, credentials: Credentials): void;
clearCredentialsByURI(uri: string): void;

interface Credentials {
  token?: string;
  username?: string;
  password?: string;
  email?: string;
  auth?: string;
  certfile?: string;
  keyfile?: string;
}

Credential Management

Utility Functions

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

// Main utility exports
const { 
  parseField,
  envReplace, 
  nerfDart,
  setEnvs,
  typeDescription,
  Umask
} = require('@npmcli/config/lib/...');

// Type definitions
const typeDefs = Config.typeDefs;

Utility Functions

Error Handling

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

const { ErrInvalidAuth } = require('@npmcli/config/lib/errors');

class ErrInvalidAuth extends Error {
  constructor(message: string, registry: string);
  registry: string;
}

Error Handling

Types

// Configuration data structure
interface ConfigData {
  data: Record<string, any>;
  source: string;
}

// Validation problem reporting
interface ValidationProblem {
  path: string;
  message: string;
}

// Type definition structure
interface TypeDefinition {
  type: any;
  validate?: (data: any, key: string, value: any) => boolean;
  description?: string;
}