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
```