npm-registry

name	npm-registry
description	Run and configure a local npm registry proxy that caches packages from upstream and serves them offline with the lpr CLI

npm-registry

Use this skill when you need to set up, configure, or interact with the local package registry proxy.

Starting the registry

lpr start

The registry starts on port 4873 (npm protocol) and the web dashboard on port 3600.

Configuring npm to use lpr

Project-level (.npmrc in project root)

registry=http://localhost:4873

Global

npm config set registry http://localhost:4873

Scoped packages only

@myco:registry=http://localhost:4873

This routes only @myco/* packages through lpr, leaving others going to the default registry.

lpr.yaml configuration

port: 4873                       # Registry port
web_port: 3600                   # Web UI port
upstream: https://registry.npmjs.org
cache_ttl: 86400                 # 24 hours
storage: ./lpr-packages          # Tarball storage directory

scope_map:
  "@myco": local                 # Always serve from local published packages
  "@azure": https://pkgs.dev.azure.com/myorg/_packaging/feed/npm/registry

scope_map values

• local - only serve from locally published packages, never proxy upstream
• A URL string - proxy this scope to the given registry instead of the default upstream

Cache behavior

• Packages are cached on first download from upstream
• Cache expires after cache_ttl seconds (default: 24h)
• Expired cache entries are re-fetched from upstream on next install
• Tarballs are stored permanently; only metadata has TTL
• Hit count is tracked per package version

Viewing cache

lpr cache ls              # Show all cached packages with hit counts
lpr cache clear           # Remove all cached packages
lpr cache clear lodash    # Remove cache for a specific package

Environment variables

Variable	Default	Description
LPR_PORT	4873	Registry proxy port
LPR_WEB_PORT	3600	Web dashboard port
LPR_UPSTREAM	https://registry.npmjs.org	Default upstream registry
LPR_CACHE_TTL	86400	Metadata cache TTL in seconds
LPR_STORAGE	./lpr-packages	Tarball storage directory
LPR_WEB_ENABLED	1	Set to 0 to disable web UI

Web dashboard

Open http://localhost:3600 to view:

• Dashboard with stats (hits, misses, storage size, package count)
• Published packages list
• Cached packages with hit counts and expiry
• Live request log with source badges (local/cached/upstream/miss)
• Settings and npmrc snippet generator

Offline operation

Packages that were previously downloaded and are still within TTL are served from disk without any network access. After TTL expires they will be re-fetched, but tarballs themselves never expire from disk.

To force offline-only mode: set LPR_UPSTREAM=http://127.0.0.1:1 (unreachable), which causes all non-cached requests to fail with a miss.

Request sources

Badge	Meaning
local	Served from locally published package
cached	Served from disk cache
upstream	Fetched from upstream and cached
miss	Not found in local or upstream