or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfiguration.mdhttp-api.mdindex.mdserver-management.mdutilities.md
tile.json

tessl/npm-verdaccio

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/verdaccio@6.1.x

To install, run

npx @tessl/cli install tessl/npm-verdaccio@6.1.0

index.mddocs/

Verdaccio

Verdaccio is a lightweight private npm proxy registry application that provides zero-configuration package management for private npm packages. It serves as a local registry server that can proxy other registries like npmjs.org while caching downloaded modules, with its own storage for private packages. The application supports authentication, access control, a web interface, and extensible storage backends through plugins.

Package Information

  • Package Name: verdaccio
  • Package Type: npm (application)
  • Language: TypeScript
  • Installation: npm install -g verdaccio (for CLI) or npm install verdaccio (for programmatic use)

Core Imports

For programmatic server usage:

import { runServer, startVerdaccio, parseConfigFile, ConfigBuilder } from "verdaccio";

For CommonJS:

const { runServer, startVerdaccio, parseConfigFile, ConfigBuilder } = require("verdaccio");

Basic Usage

Running as CLI Application

# Start server with default configuration
verdaccio

# Start with custom configuration
verdaccio --config /path/to/config.yaml

# Start on custom port
verdaccio --listen 5000

# Show version
verdaccio --version

# Show system info
verdaccio --info

Programmatic Server Usage

import { runServer } from "verdaccio";

// Start server with default configuration
const server = await runServer();
server.listen(4873, () => {
  console.log("Verdaccio started on http://localhost:4873");
});

// Start with custom configuration file
const serverWithConfig = await runServer("/path/to/config.yaml");
serverWithConfig.listen(4873);

Architecture

Verdaccio is built around several key components:

  • Server Factory: Core server creation functions (runServer, startVerdaccio) for programmatic and CLI usage
  • Express API: RESTful HTTP API implementing npm registry protocol for package operations
  • Storage System: Pluggable storage backends with default file system storage
  • Authentication: Configurable auth providers with built-in htpasswd support
  • Proxy/Uplinks: Transparent proxying to upstream registries like npmjs.org
  • Web Interface: Optional web UI for package browsing and management
  • Plugin System: Extensible middleware and storage plugin architecture

Capabilities

Server Management

Core server creation and lifecycle management for running Verdaccio programmatically or via CLI.

/**
 * Primary server factory function for programmatic usage
 * @param config - Configuration file path (string) or undefined for default
 * @returns Promise resolving to HTTP/HTTPS server instance
 */
function runServer(config?: string): Promise<any>;

/**
 * Legacy server bootstrap function (deprecated)
 * @param config - Configuration object
 * @param cliListen - Listen address from CLI
 * @param configPath - Path to configuration file
 * @param pkgVersion - Package version
 * @param pkgName - Package name
 * @param callback - Server callback function
 */
function startVerdaccio(
  config: any,
  cliListen: string,
  configPath: string,
  pkgVersion: string,
  pkgName: string,
  callback: Callback
): void;

Server Management

Command Line Interface

CLI commands for server operation, configuration, and system information.

class InitCommand extends Command {
  listen: string;
  config: string;
  execute(): Promise<void>;
}

class InfoCommand extends Command {
  execute(): Promise<void>;
}

class VersionCommand extends Command {
  execute(): Promise<void>;
}

Command Line Interface

HTTP Registry API

RESTful API implementing npm registry protocol for package publishing, installation, and management.

// Package management endpoints
app.get('/:package', packageHandler);
app.put('/:package', publishHandler);
app.delete('/:package/-rev/:revision', unpublishHandler);

// User management endpoints  
app.put('/-/user/:user', userHandler);
app.get('/-/whoami', whoamiHandler);

// Search and discovery
app.get('/-/v1/search', searchHandler);
app.get('/-/all', allPackagesHandler);

// Distribution tags
app.get('/:package/:tag', distTagHandler);
app.put('/:package/:tag', updateDistTagHandler);

HTTP Registry API

Configuration Management

Configuration parsing, validation, and management utilities.

/**
 * Parse Verdaccio configuration file
 * @param configPath - Path to configuration file
 * @returns Parsed configuration object
 */
function parseConfigFile(configPath: string): any;

/**
 * Configuration builder utility class
 */
class ConfigBuilder {
  // Configuration builder methods
}

Configuration Management

Utility Functions

Core utility functions for package management, validation, and data processing.

function isObject(obj: any): boolean;
function tagVersion(data: Manifest, version: string, tag: string): boolean;
function getVersion(pkg: Manifest, version: any): Version | void;
function parseAddress(urlAddress: any): any;
function semverSort(listVersions: string[]): string[];
function normalizeDistTags(pkg: Manifest): void;
function parseInterval(interval: any): number;
function folderExists(path: string): boolean;
function fileExists(path: string): boolean;

Utility Functions

Types

interface Callback {
  (webServer: any, addr: any, pkgName: string, pkgVersion: string): void;
}

interface Manifest {
  versions: { [version: string]: Version };
  [key: string]: any;
}

interface Version {
  name: string;
  version: string;
  [key: string]: any;
}

interface Config {
  storage: string;
  auth?: any;
  uplinks?: { [name: string]: any };
  packages?: { [pattern: string]: any };
  listen?: string | string[];
  https?: any;
  web?: any;
  logs?: any;
  [key: string]: any;
}