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. |
Create the repositories
Section titled “Create the repositories”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"]}}'Configure the client
Section titled “Configure the client”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.
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:
npm config set registry https://entrepot.example.com/repository/npm-group/npm config set //entrepot.example.com/repository/npm-group/:_authToken "$ENTREPOT_TOKEN"pnpm reads the same .npmrc:
registry=https://entrepot.example.com/repository/npm-group///entrepot.example.com/repository/npm-group/:_authToken=${ENTREPOT_TOKEN}pnpm installnpmRegistryServer: "https://entrepot.example.com/repository/npm-group/"npmAlwaysAuth: truenpmAuthToken: "${ENTREPOT_TOKEN}"Yarn classic reads .npmrc like npm does; yarn config set registry https://entrepot.example.com/repository/npm-group/ also works.
Only route your scope through Entrepot
Section titled “Only route your scope through Entrepot”If you only want your own scope from Entrepot and everything else from the public registry:
@acme:registry=https://entrepot.example.com/repository/npm-internal///entrepot.example.com/repository/npm-internal/:_authToken=${ENTREPOT_TOKEN}Publish
Section titled “Publish”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:
{ "name": "@acme/widgets", "version": "1.2.0", "publishConfig": { "registry": "https://entrepot.example.com/repository/npm-internal/" }}Other registry operations:
R=https://entrepot.example.com/repository/npm-internal/npm dist-tag add @acme/widgets@1.2.0 stable --registry $Rnpm deprecate @acme/widgets@1.1.0 "use 1.2" --registry $Rnpm unpublish @acme/widgets@1.1.0 --registry $R # needs the delete actionnpm whoami --registry $Rnpm search widgets --registry $R
# interactive login: use your Entrepot token as the password (any username)npm login --registry $R --auth-type=legacyPublishing a version that already exists returns 409 unless
hosted.allowRedeploy is enabled.
From GitLab CI
Section titled “From GitLab CI”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 publishSee GitLab CI for the trust policy and role binding.
Troubleshooting
Section titled “Troubleshooting”E401/ENEEDAUTH— the_authTokenline 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 adeveloperbinding on the hosted repository.E403 … waive or fix to download— the tarball is quarantined. Packuments are never blocked, sonpm viewstill works.- A public package with your internal name appears — make sure you
install from a group with
preferHostedand 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.jsonpoints at another registry — lockfiles record resolved tarball URLs. Regenerate the lockfile after switching registries.