tessl/npm-verdaccio

A lightweight private npm proxy registry application with comprehensive package management, authentication, and web interface capabilities

—

Pending

Overview

Eval results

Files

Configuration Management

Name: tessl/npm-verdaccio
Author: tessl

Configuration parsing, validation, and management utilities for Verdaccio server setup and customization.

Capabilities

Configuration File Parsing

Parse and validate Verdaccio configuration files with automatic path resolution.

/**
 * Parse Verdaccio configuration file with validation and defaults
 * @param configPath - Absolute path to configuration file (YAML format)
 * @returns Parsed and validated configuration object
 * @throws Error if file doesn't exist or contains invalid YAML
 */
function parseConfigFile(configPath: string): any;

Usage Examples:

import { parseConfigFile } from "verdaccio";

// Parse configuration file
const config = parseConfigFile("/path/to/config.yaml");

// Configuration is ready to use
const server = await runServer(config);

Configuration Builder

Utility class for programmatically building Verdaccio configurations.

/**
 * Configuration builder utility class for programmatic config creation
 */
class ConfigBuilder {
  /**
   * Build configuration with validation and defaults
   */
  static build(options: any): any;
}

Configuration File Discovery

Locate Verdaccio configuration files using standard search paths.

/**
 * Find configuration file using standard search locations
 * @param customPath - Optional custom configuration file path
 * @returns Absolute path to configuration file
 * @throws Error if no configuration file found
 */
function findConfigFile(customPath?: string): string;

Search order:

Custom path (if provided)
./config.yaml (current directory)
~/.config/verdaccio/config.yaml (user config)
/etc/verdaccio/config.yaml (system config)

Configuration Structure

Core Configuration Options

# Storage location for packages and metadata
storage: ./storage

# Authentication providers
auth:
  htpasswd:
    file: ./htpasswd
    max_users: 1000

# Upstream registry links
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    timeout: 30s
    max_fails: 2

# Package access control
packages:
  '@private/*':
    access: $authenticated
    publish: $authenticated
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

# Server settings
listen: 0.0.0.0:4873

# Web interface
web:
  enable: true
  title: Verdaccio

# Logging configuration
logs:
  - { type: stdout, format: pretty, level: info }

Storage Configuration

interface StorageConfig {
  /** Storage directory path */
  storage: string;
  /** Plugin configuration for custom storage */
  store?: {
    [pluginName: string]: any;
  };
}

Authentication Configuration

interface AuthConfig {
  /** Built-in htpasswd authentication */
  htpasswd?: {
    file: string;
    max_users?: number;
  };
  /** Plugin-based authentication */
  [pluginName: string]: any;
}

Uplinks Configuration

interface UplinksConfig {
  [uplinkName: string]: {
    url: string;
    timeout?: string;
    max_fails?: number;
    fail_timeout?: string;
    headers?: { [key: string]: string };
    ca?: string;
    cert?: string;
    key?: string;
    strict_ssl?: boolean;
  };
}

Packages Configuration

interface PackagesConfig {
  [pattern: string]: {
    access: string | string[];
    publish: string | string[];
    proxy?: string | string[];
    storage?: string;
  };
}

Server Configuration

interface ServerConfig {
  /** Listen address and port */
  listen?: string | string[];
  /** HTTPS configuration */
  https?: {
    key?: string;
    cert?: string;
    ca?: string;
    pfx?: string;
    passphrase?: string;
  };
  /** Keep-alive timeout in seconds */
  keepAliveTimeout?: number;
  /** Trust proxy headers */
  trustProxy?: boolean | string | string[];
}

Web Interface Configuration

interface WebConfig {
  /** Enable web interface */
  enable?: boolean;
  /** Web interface title */
  title?: string;
  /** Custom logo URL */
  logo?: string;
  /** Primary color theme */
  primary_color?: string;
  /** Login functionality */
  login?: boolean;
  /** Package scope filters */
  scope?: string;
}

Logging Configuration

interface LogConfig {
  type: 'stdout' | 'stderr' | 'file';
  format: 'pretty' | 'pretty-timestamped' | 'json';
  level: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
  path?: string; // for file type
}

Configuration Validation

Required Fields

storage: Must be a valid directory path
auth: At least one authentication method
packages: At least one package pattern

Optional Fields

uplinks: Defaults to npmjs.org if not specified
listen: Defaults to localhost:4873
web: Defaults to enabled
logs: Defaults to pretty stdout logging

Environment Variable Substitution

Configuration files support environment variable substitution:

storage: ${VERDACCIO_STORAGE_PATH:-./storage}
listen: ${VERDACCIO_PORT:-4873}

auth:
  htpasswd:
    file: ${VERDACCIO_HTPASSWD_FILE:-./htpasswd}

Migration and Compatibility

Configuration Migration

V5 to V6 configuration migration utilities
Automatic handling of deprecated configuration options
Warning messages for outdated configuration patterns

Backward Compatibility

Support for legacy configuration formats
Graceful handling of removed options
Migration guides for major version upgrades

Configuration Examples

Minimal Configuration

storage: ./storage
auth:
  htpasswd:
    file: ./htpasswd
packages:
  '**':
    access: $all
    publish: $authenticated

Enterprise Configuration

storage: /var/lib/verdaccio/storage

auth:
  ldap:
    url: ldap://ldap.company.com
    baseDN: 'ou=people,dc=company,dc=com'

uplinks:
  npmjs:
    url: https://registry.npmjs.org/
  internal:
    url: https://internal-registry.company.com/

packages:
  '@company/*':
    access: $authenticated
    publish: $authenticated
    storage: company-packages
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

listen: 0.0.0.0:4873

https:
  key: /etc/ssl/private/verdaccio.key
  cert: /etc/ssl/certs/verdaccio.crt

web:
  title: Company NPM Registry
  logo: https://company.com/logo.png
  primary_color: "#4CAF50"

logs:
  - { type: file, path: /var/log/verdaccio/verdaccio.log, level: info }

Install with Tessl CLI