Skip to content

npm

Entrepot speaks the npm registry protocol: packuments (full and abbreviated), tarballs, npm publish, dist-tags, deprecate, unpublish, search, whoami and audit. Scoped packages (@acme/widgets) work everywhere.

Kind Behaviour
hosted npm publish target. Entrepot computes shasum and integrity itself on publish.
proxy Caches packuments and tarballs from registry.npmjs.org (or any registry), verifying tarball integrity before caching. npm audit is forwarded to the upstream.
group Merges packuments from its members. With preferHosted (default), if a hosted member has a package name, proxy members never contribute versions or tarballs for it.
Terminal window
api -X POST $E/api/v1/repositories -d '{"name":"npm-proxy","format":"npm","kind":"proxy","blobStore":"default","proxy":{"remoteUrl":"https://registry.npmjs.org"}}'
api -X POST $E/api/v1/repositories -d '{"name":"npm-internal","format":"npm","kind":"hosted","blobStore":"default"}'
api -X POST $E/api/v1/repositories -d '{"name":"npm-group","format":"npm","kind":"group","blobStore":"default","group":{"members":["npm-internal","npm-proxy"]}}'

Install from the group; publish to the hosted repository. npm matches auth tokens by URL prefix, so give each repository you talk to its own _authToken line.

.npmrc
registry=https://entrepot.example.com/repository/npm-group/
//entrepot.example.com/repository/npm-group/:_authToken=${ENTREPOT_TOKEN}
//entrepot.example.com/repository/npm-internal/:_authToken=${ENTREPOT_TOKEN}

npm expands ${ENTREPOT_TOKEN} from the environment, so the file can be committed. Or set it from the command line:

Terminal window
npm config set registry https://entrepot.example.com/repository/npm-group/
npm config set //entrepot.example.com/repository/npm-group/:_authToken "$ENTREPOT_TOKEN"

If you only want your own scope from Entrepot and everything else from the public registry:

.npmrc
@acme:registry=https://entrepot.example.com/repository/npm-internal/
//entrepot.example.com/repository/npm-internal/:_authToken=${ENTREPOT_TOKEN}
Terminal window
npm publish --registry https://entrepot.example.com/repository/npm-internal/

Or set publishConfig in package.json so a plain npm publish goes to the right place:

package.json
{
"name": "@acme/widgets",
"version": "1.2.0",
"publishConfig": { "registry": "https://entrepot.example.com/repository/npm-internal/" }
}

Other registry operations:

Terminal window
R=https://entrepot.example.com/repository/npm-internal/
npm dist-tag add @acme/widgets@1.2.0 stable --registry $R
npm deprecate @acme/widgets@1.1.0 "use 1.2" --registry $R
npm unpublish @acme/widgets@1.1.0 --registry $R # needs the delete action
npm whoami --registry $R
npm search widgets --registry $R
# interactive login: use your Entrepot token as the password (any username)
npm login --registry $R --auth-type=legacy

Publishing a version that already exists returns 409 unless hosted.allowRedeploy is enabled.

publish:
image: node:22
id_tokens:
ENTREPOT_ID_TOKEN:
aud: https://entrepot.example.com
script:
- npm config set registry https://entrepot.example.com/repository/npm-internal/
- npm config set //entrepot.example.com/repository/npm-internal/:_authToken "$ENTREPOT_ID_TOKEN"
- npm publish

See GitLab CI for the trust policy and role binding.

  • E401 / ENEEDAUTH — the _authToken line must match the registry URL exactly, including /repository/<name>/ and the trailing slash.
  • E403 … is not permitted to write — your token can read but not publish; ask for a developer binding on the hosted repository.
  • E403 … waive or fix to download — the tarball is quarantined. Packuments are never blocked, so npm view still works.
  • A public package with your internal name appears — make sure you install from a group with preferHosted and add a routing rule for your scope. See Dependency confusion.
  • New upstream versions are missing — packuments are cached for proxy.metadataTtlSeconds (default 3600).
  • package-lock.json points at another registry — lockfiles record resolved tarball URLs. Regenerate the lockfile after switching registries.