@packall/registry-npm

An npm-protocol Registry backend for @packall/core. It works with the public npm registry and npm-compatible registries such as Artifactory, Nexus, Verdaccio, and GitHub Packages.

Install

npm install @packall/registry-npm @packall/core effect

Configure a registry

The backend accepts an explicit registry or parsed .npmrc configuration. It supports the same practical configuration shape as npm:

registry=https://artifactory.example/api/npm/npm-remote/
@acme:registry=https://artifactory.example/api/npm/acme/
//artifactory.example/api/npm/:_authToken=${NPM_TOKEN}

Use parseNpmrc when an application already has the file contents, or let the Node entrypoint load project and user configuration in npm's precedence order. Credentials support bearer tokens, pre-encoded basic auth, and username/_password; secrets stay redacted until the authorization header is built.

TLS trust

strict-ssl, cafile and ca/ca[] are read from the same configuration. They are not applied here: TLS belongs to whatever opens the socket, so tlsConfigFor reports what was configured and the host applies it to its own HTTP client. resolveTls, in the /node entrypoint, is the same thing with cafile read from disk.

import * as Effect from "effect/Effect";
import { resolveTls } from "@packall/registry-npm/node";

// Needs a FileSystem in context, since this is the variant that reads `cafile`.
const program = Effect.gen(function* () {
	const { settings, warnings } = yield* resolveTls(npmrc);
	// settings: { rejectUnauthorized: boolean, ca: ReadonlyArray<string> }
});

An unreadable cafile is reported in warnings rather than failing — the system store may still be enough, and a certificate error that names no file is worse than a warning that does.

Backend behavior

The backend speaks the two npm registry endpoints needed by the engine: package metadata and tarball downloads. It performs a bounded preflight check, applies request and preflight timeouts, and caches packuments during a run. Retries use capped exponential backoff with jitter, but only for transient network errors, HTTP 5xx responses, and HTTP 429. Authentication errors, missing packages, integrity failures, and other permanent responses are not retried.

import { layer as npmRegistry } from "@packall/registry-npm";

const registry = npmRegistry({
	registry: "https://registry.example/",
	requestTimeoutMs: 10_000,
	rewriteTarballHost: false,
});

Set rewriteTarballHost: true when a proxy returns tarball URLs on a host or path that should be replaced by the configured registry. The default uses the URL returned in the packument.

See the packall documentation and the @packall/registry-npm API reference for the complete API.

License

MIT