verdaccio

Verdaccio is a private npm-compatible package registry you run yourself, letting teams publish and consume private packages without sending code to a public registry. It ships with its own lightweight built-in storage so there’s no separate database to provision, and it proxies public registries like npmjs.org, caching every module it fetches to speed up installs and provide a safety net when the upstream registry is unavailable.

Beyond a single binary, Verdaccio is built as a monorepo of composable packages — a CLI, a Node API, an Express-based HTTP server, a pluggable storage layer, and an authentication/plugin system — so teams can extend it with custom storage backends (S3, Google Cloud Storage), authentication schemes, or package-filtering rules instead of being locked into the defaults.

What You Get

• A single self-hosted binary that speaks the full npm registry protocol, installable via npm, Docker, or an official Helm chart.
• Built-in local storage for private packages with no external database required to get started.
• Transparent proxy caching of upstream registries (e.g. npmjs.org), so cached tarballs remain available even during upstream outages.
• A plugin architecture for swapping in alternative storage backends (S3, Google Cloud Storage), authentication providers, and package filters.
• A web UI for browsing packages, plus verified compatibility with the npm, Yarn, pnpm, Bun, and Deno CLIs.

Common Use Cases

• Hosting private company packages without exposing source code to a public registry.
• Caching npmjs.org downloads across a fleet of CI machines to cut install latency and reduce exposure to upstream outages.
• Overriding a public package with a patched local version while waiting on an upstream pull request to merge.
• Running a fast, disposable registry inside CI pipelines for end-to-end publish/install testing.

Under The Hood

Architecture Verdaccio is organized as a pnpm-workspace monorepo (packages/) split into a thin CLI entrypoint (packages/verdaccio, whose src/index.ts re-exports runServer from @verdaccio/node-api wired to startServer from @verdaccio/server, with bin/verdaccio invoking @verdaccio/cli’s runCli()), a request-handling layer (@verdaccio/server plus @verdaccio/middleware’s modular Express middlewares for auth, rate-limiting, dotfiles, error handling, and web rendering), a storage layer (@verdaccio/store’s storage.ts orchestrating ProxyStorage from @verdaccio/proxy, Search from @verdaccio/search, and tarball/version utilities from @verdaccio/core and @verdaccio/tarball), and a plugin surface (packages/plugins/{audit,auth-memory,htpasswd,local-storage,memory,package-filter,ui-theme}) implementing pluginUtils interfaces exported from @verdaccio/core. This separation means storage, auth, and package-filtering can each be swapped via config without touching the HTTP layer.

Tech Stack Verdaccio is a TypeScript/Node.js monorepo (Node 24+ for the active development branch) managed with pnpm workspaces and Vite for building each package, with Express-based HTTP handling via @verdaccio/middleware and lodash-es for utilities. Testing runs on Vitest plus Cypress for UI end-to-end flows, alongside a separate e2e-cli/e2e-ui matrix that exercises npm, Yarn, pnpm, Bun, and Deno against a running instance. Linting and formatting are handled by oxlint and oxfmt, changesets drive versioned releases across the workspace’s many packages, and deployment targets include an official Dockerfile, a Helm chart, and global npm/yarn/pnpm installs.

Code Quality The repo contains an extensive set of spec/test files across its packages, each colocating its own suite and running through a workspace-wide test command via Vitest, with coverage tracked and generated/build artifacts explicitly excluded. TypeScript is used throughout with a shared base config, giving static typing across public plugin interfaces. oxlint enforces linting against a documented warning budget, Husky runs pre-commit hooks, and CI plus the external e2e matrix provide both unit-level and full end-to-end coverage against real package-manager clients — this reads as a mature, well-tested codebase.

What Makes It Unique Unlike registry proxies that only cache tarballs, Verdaccio’s uplink model lets an admin chain multiple upstream registries and lets a local publish shadow/override an existing public package under the same name, a capability documented as a first-class workflow rather than a workaround. Its plugin system (storage, auth, package-filter, audit) is exposed as first-class TypeScript interfaces, letting third parties ship registry backends or custom auth without forking, and the project maintains a dedicated end-to-end test matrix across essentially every major JS package manager — a level of cross-client compatibility testing uncommon even among registry-proxy competitors.