npm-registry

# npm-registry

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

## Starting the registry

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

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

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