modera/npm-static-registry repository overview

⁠npm-static-registry

npm-static-registry is a lightweight CLI tool for managing a static NPM registry. It provides commands for building package tarballs, generating NPM-compatible metadata.json files, and restoring tarballs from a CDN or remote storage.

Useful for:

• Offline NPM registries
• CDN/S3-backed static registries
• Immutable and reproducible builds
• Internal enterprise package mirrors

⁠Features

Environment variables:

• NPM_STATIC_REGISTRY_CDN_BASE_URL — CDN base URL (remote source of tarballs)
• NPM_STATIC_REGISTRY_CDN_ROOT — local filesystem root for tarballs and metadata

These variables define how the registry is stored and accessed both locally and remotely.

⁠Build tarball

Creates an NPM-compatible .tgz archive from a local package directory and writes it into:

scoped:   ${NPM_STATIC_REGISTRY_CDN_ROOT}/<scope>/<name>/<name>-<version>.tgz
unscoped: ${NPM_STATIC_REGISTRY_CDN_ROOT}/<name>/<name>-<version>.tgz

Example:

npm-static-registry build-tarball ./packages/my-pkg

⁠Generate metadata

Reads tarballs from ${NPM_STATIC_REGISTRY_CDN_ROOT} and generates a static NPM-compatible metadata.json:

npm-static-registry generate-metadata @scope/my-pkg

⁠Restore tarballs from CDN

Downloads tarballs from remote metadata and stores them into:

scoped:   ${NPM_STATIC_REGISTRY_CDN_ROOT}/<scope>/<name>
unscoped: ${NPM_STATIC_REGISTRY_CDN_ROOT}/<name>

Example:

npm-static-registry restore-tarballs @scope/my-pkg

⁠Environment variables

⁠NPM_STATIC_REGISTRY_CDN_BASE_URL

Base URL used for downloading tarballs or generating remote paths.

Default (build-time):

https://cdn.example.com/npm-registry

Override:

export NPM_STATIC_REGISTRY_CDN_BASE_URL="https://cdn.my-company.com/npm"

⁠NPM_STATIC_REGISTRY_CDN_ROOT

Local directory where tarballs and metadata are stored.

Default (build-time):

./npm-registry

Override:

export NPM_STATIC_REGISTRY_CDN_ROOT="/data/npm-registry"

⁠Usage

Run help:

docker run --rm modera/npm-static-registry:<TAG>

Run with environment variables:

docker run --rm \
    -e NPM_STATIC_REGISTRY_CDN_BASE_URL="https://cdn.example.com/npm" \
    -e NPM_STATIC_REGISTRY_CDN_ROOT="/registry" \
    modera/npm-static-registry:<TAG>

⁠License

This project is licensed under the MIT License.