Verdaccio — Lightweight Private npm Proxy Registry

Introduction

Verdaccio is a lightweight, zero-config private npm registry and proxy. It stores published packages on disk, forwards requests for public packages to npmjs.org (caching them locally), and works out of the box for teams that need offline access or private modules.

What Verdaccio Does

• Acts as a transparent proxy and cache for the public npm registry
• Hosts private packages that never leave your network
• Supports scoped packages, token-based auth, and publish access control
• Provides a web UI for browsing packages and their metadata
• Integrates with CI/CD pipelines as a drop-in npm registry replacement

Architecture Overview

Verdaccio is a single Node.js process that serves an npm-compatible HTTP API. Packages are stored on disk by default (configurable to S3, GCS, or other storage backends via plugins). An in-memory metadata cache speeds up lookups. Uplink configuration determines which remote registries to proxy and how long to cache tarball and metadata responses.

Self-Hosting & Configuration

• Config lives in ~/.config/verdaccio/config.yaml by default
• Set uplinks to define upstream registries (npmjs, GitHub Packages, etc.)
• Use packages section to control publish/access rules per scope or pattern
• Deploy via Docker: docker run -d -p 4873:4873 verdaccio/verdaccio
• Add htpasswd, LDAP, or GitLab auth plugins for team access control

Key Features

• Zero-config startup: works immediately after install with sane defaults
• Offline mode: once cached, packages are available without internet
• Plugin ecosystem: storage backends, auth providers, middleware hooks
• Web dashboard: search, browse readme, and view version history
• Multi-registry uplinks: proxy multiple registries with priority ordering

Comparison with Similar Tools

• Nexus Repository — full artifact manager for Maven, Docker, npm; heavier setup
• Artifactory — enterprise-grade; Verdaccio is simpler and fully open source
• GitHub Packages — cloud-hosted; Verdaccio runs on-prem with no vendor lock-in
• npm Enterprise — deprecated in favor of GitHub Packages; Verdaccio is actively maintained

FAQ

Q: Does Verdaccio support Yarn and pnpm? A: Yes. Any npm-compatible client works because Verdaccio implements the standard npm registry API.

Q: Can I use Verdaccio as a caching proxy only, without publishing? A: Yes. By default it proxies all requests to npmjs.org. Disable publish access in the config if you want a read-only cache.

Q: How much disk space does it use? A: Only cached and published packages consume disk. A typical project's dependency tree might use a few hundred MB.

Q: Is there clustering or replication support? A: Verdaccio runs as a single process. For high availability, use a shared storage backend (NFS, S3) behind a load balancer.

Sources

• https://github.com/verdaccio/verdaccio
• https://verdaccio.org/docs/what-is-verdaccio