0
# Verdaccio
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: verdaccio
7
- **Package Type**: npm (application)
8
- **Language**: TypeScript
9
- **Installation**: `npm install -g verdaccio` (for CLI) or `npm install verdaccio` (for programmatic use)
10

11
## Core Imports
12

13
For programmatic server usage:
14

15
```typescript
16
import { runServer, startVerdaccio, parseConfigFile, ConfigBuilder } from "verdaccio";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { runServer, startVerdaccio, parseConfigFile, ConfigBuilder } = require("verdaccio");
23
```
24

25
## Basic Usage
26

27
### Running as CLI Application
28

29
```bash
30
# Start server with default configuration
31
verdaccio
32

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

36
# Start on custom port
37
verdaccio --listen 5000
38

39
# Show version
40
verdaccio --version
41

42
# Show system info
43
verdaccio --info
44
```
45

46
### Programmatic Server Usage
47

48
```typescript
49
import { runServer } from "verdaccio";
50

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

57
// Start with custom configuration file
58
const serverWithConfig = await runServer("/path/to/config.yaml");
59
serverWithConfig.listen(4873);
60
```
61

62
## Architecture
63

64
Verdaccio is built around several key components:
65

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

74
## Capabilities
75

76
### Server Management
77

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

80
```typescript { .api }
81
/**
82
 * Primary server factory function for programmatic usage
83
 * @param config - Configuration file path (string) or undefined for default
84
 * @returns Promise resolving to HTTP/HTTPS server instance
85
 */
86
function runServer(config?: string): Promise<any>;
87

88
/**
89
 * Legacy server bootstrap function (deprecated)
90
 * @param config - Configuration object
91
 * @param cliListen - Listen address from CLI
92
 * @param configPath - Path to configuration file
93
 * @param pkgVersion - Package version
94
 * @param pkgName - Package name
95
 * @param callback - Server callback function
96
 */
97
function startVerdaccio(
98
  config: any,
99
  cliListen: string,
100
  configPath: string,
101
  pkgVersion: string,
102
  pkgName: string,
103
  callback: Callback
104
): void;
105
```
106

107
[Server Management](./server-management.md)
108

109
### Command Line Interface
110

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

113
```typescript { .api }
114
class InitCommand extends Command {
115
  listen: string;
116
  config: string;
117
  execute(): Promise<void>;
118
}
119

120
class InfoCommand extends Command {
121
  execute(): Promise<void>;
122
}
123

124
class VersionCommand extends Command {
125
  execute(): Promise<void>;
126
}
127
```
128

129
[Command Line Interface](./cli.md)
130

131
### HTTP Registry API
132

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

135
```typescript { .api }
136
// Package management endpoints
137
app.get('/:package', packageHandler);
138
app.put('/:package', publishHandler);
139
app.delete('/:package/-rev/:revision', unpublishHandler);
140

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

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

149
// Distribution tags
150
app.get('/:package/:tag', distTagHandler);
151
app.put('/:package/:tag', updateDistTagHandler);
152
```
153

154
[HTTP Registry API](./http-api.md)
155

156
### Configuration Management
157

158
Configuration parsing, validation, and management utilities.
159

160
```typescript { .api }
161
/**
162
 * Parse Verdaccio configuration file
163
 * @param configPath - Path to configuration file
164
 * @returns Parsed configuration object
165
 */
166
function parseConfigFile(configPath: string): any;
167

168
/**
169
 * Configuration builder utility class
170
 */
171
class ConfigBuilder {
172
  // Configuration builder methods
173
}
174
```
175

176
[Configuration Management](./configuration.md)
177

178
### Utility Functions
179

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

182
```typescript { .api }
183
function isObject(obj: any): boolean;
184
function tagVersion(data: Manifest, version: string, tag: string): boolean;
185
function getVersion(pkg: Manifest, version: any): Version | void;
186
function parseAddress(urlAddress: any): any;
187
function semverSort(listVersions: string[]): string[];
188
function normalizeDistTags(pkg: Manifest): void;
189
function parseInterval(interval: any): number;
190
function folderExists(path: string): boolean;
191
function fileExists(path: string): boolean;
192
```
193

194
[Utility Functions](./utilities.md)
195

196
## Types
197

198
```typescript { .api }
199
interface Callback {
200
  (webServer: any, addr: any, pkgName: string, pkgVersion: string): void;
201
}
202

203
interface Manifest {
204
  versions: { [version: string]: Version };
205
  [key: string]: any;
206
}
207

208
interface Version {
209
  name: string;
210
  version: string;
211
  [key: string]: any;
212
}
213

214
interface Config {
215
  storage: string;
216
  auth?: any;
217
  uplinks?: { [name: string]: any };
218
  packages?: { [pattern: string]: any };
219
  listen?: string | string[];
220
  https?: any;
221
  web?: any;
222
  logs?: any;
223
  [key: string]: any;
224
}
225
```