Skip to content
[ PIER ]

npm Registry — Overview

TL;DR

Section titled “TL;DR”

Pier ships a full npm-compatible registry as part of the same Rust binary that runs your containers. No Verdaccio container, no extra database — open https://your-pier-host/registry/npm/, mint a token from the panel, write three lines into .npmrc, and you have a private + proxy registry that the whole team can use.

It speaks the npm registry HTTP protocol end-to-end, so npm, yarn (1 and 2/3/4), pnpm and bun all work against it without bespoke client code.

What it does

Section titled “What it does”
  • Private publishing. npm publish (scoped and unscoped), npm dist-tag, npm deprecate, npm unpublish. The full set of standard mutations.
  • Upstream proxy mode. Mirror registry.npmjs.org (or any compatible upstream) — packuments cached forever, tarballs pulled lazily on the first install, LRU GC keeps the on-disk cache under a configurable cap.
  • Web login flow. npm login --auth-type=web opens the browser, authenticates against the Pier panel (with 2FA), and drops a long-lived pier_npm_… token into .npmrc — no manual copy-paste.
  • Streamed downloads. Tarballs are served via axum::Body::from_stream — Pier doesn’t buffer a 200 MiB tarball in RAM.
  • Rate-limited per-route. Public reads, admin mutations and npm publish each have their own per-IP budget.

Who it’s for

Section titled “Who it’s for”

Pier’s registry is a fit if you:

  • Want a self-hosted alternative to Verdaccio without the extra container and database.
  • Have a small team that wants one .npmrc URL for both private packages and public dependencies.
  • Need installs to keep working when npmjs.org is down.
  • Want audit visibility — see which public packages your team actually uses.
  • Already run Pier for containers and don’t want to operate a second daemon.

What’s not in v1

Section titled “What’s not in v1”
  • npm search — no /-/v1/search endpoint yet. Discovery is via the Pier UI.
  • npm owner / RBAC — single-owner model today: the publisher of a version controls deprecate / unpublish for that version, admin overrides. Multi-maintainer ownership lands later.
  • npm audit — the natural way to ship this is after the upstream-proxy work, so the audit payloads can be passed through to npmjs.org. Both are tracked on the roadmap.
  • npm star/unstar — explicitly not planned. The UI exposes a “pin” toggle for the Mirror tab, which solves the same problem better.

Everything else from the standard npm CLI works against Pier today.

Architecture at a glance

Section titled “Architecture at a glance”
npm install left-pad ─┬─► GET /registry/npm/left-pad
                       │      (packument, ETag-cached)
                       │
                       └─► GET /registry/npm/left-pad/-/left-pad-1.3.0.tgz
                              ↓ first time: upstream fetch + cache
                              ↓ next time: stream from local FS
  • Packument metadata lives in SQLite (npm_packages for the raw JSON blob, npm_versions for downloaded versions).
  • Tarballs live on the local filesystem at data/registry/{package}/{file}.tgz. Optionally mirrored to any S3-compatible cold tier (Packages → S3 configure).
  • ETag revalidation via If-None-Match → 304 short-circuit. TTL-based refresh wakes up stale entries automatically.

Next steps

Section titled “Next steps”
  1. Enable the registry and configure your first client — 5 minutes.
  2. Turn on upstream proxy mode so the team mirrors npmjs.org.
  3. Pick your client guide: npm · yarn 1.x · yarn 2/3/4 · pnpm · bun.
Section titled “Related”