Skip to content

Configure npm, Yarn and pnpm

Every client needs two things: the Provenix registry URL and a client token. Keep the token out of committed files by reading it from the PROVENIX_NPM_TOKEN environment variable.

Tested clients

Provenix's client tests run against these versions on every change:

Client Tested version Config file
npm 11.6 .npmrc
Yarn classic 1.22 .npmrc
Yarn Berry 4.5 .yarnrc.yml
pnpm 9.15 .npmrc

Older versions usually work but aren't tested. Yarn Plug'n'Play, Bun and Deno aren't supported yet.

npm, Yarn classic and pnpm

.npmrc in the project root:

registry=https://npm.example.com/
//npm.example.com/:_authToken=${PROVENIX_NPM_TOKEN}
always-auth=true
replace-registry-host=never
  • npm, Yarn classic and pnpm all expand ${PROVENIX_NPM_TOKEN} from the environment.
  • replace-registry-host=never (npm 9 and later) stops npm rewriting the download URLs Provenix serves.

Existing lockfiles

With replace-registry-host=never, npm downloads every package in package-lock.json from the URL the lockfile records. If those URLs still point at registry.npmjs.org, npm skips Provenix for them. When you move an existing project over, rewrite the lockfile's URLs as shown in Point the lockfile at Provenix too. Do the same for yarn.lock with Yarn classic.

Yarn Berry

.yarnrc.yml in the project root:

npmRegistryServer: "https://npm.example.com"
npmRegistries:
  "https://npm.example.com":
    npmAuthToken: "${PROVENIX_NPM_TOKEN}"
    npmAlwaysAuth: true
nodeLinker: node-modules

If your Provenix registry is served over plain HTTP (a local test install, for example), Yarn Berry refuses it unless the host is listed:

unsafeHttpWhitelist:
  - "localhost"

Use HTTPS everywhere else, and leave that setting out.

Check the connection

npm whoami

This prints the name of the client that owns the token, for example ci-shop-web-build. If it fails with 401, the token is missing, mistyped or has been rotated.

What Provenix doesn't accept

Provenix is a read-only registry. It refuses:

  • npm publish and npm unpublish (405),
  • npm login and npm adduser (403): use a client token instead.

Publish your own packages to your private registry. Provenix can serve them from there if your admin adds it as a scoped upstream.

npm audit keeps working: Provenix passes audit requests to the upstream registry. If upstream can't be reached, it returns an empty report rather than failing your install.