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 publishandnpm unpublish(405),npm loginandnpm 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.