<!– caps: [CAP-NPM-HOSTING] –>

npm Client

CloudRepo works with the npm CLI through your .npmrc. You authenticate as a repository user, and you can optionally exchange those credentials for a revocable bearer token.

Hosted at CloudRepo — see private npm registry hosting for plans and pricing.

Getting started — put your repository user’s credentials in .npmrc as _auth.
CI/CD — mint a bearer token with npm token create and reference it as _authToken, so the pipeline’s credential can be revoked on its own.

Prerequisites

A CloudRepo account with at least one npm repository.
A repository user to authenticate as. Create one in the admin portal under Users → Create a Repository User, then grant it access to the repositories you need. Use a dedicated user for builds rather than an owner account, so the credential can be rotated without disrupting anyone’s portal access.
npm CLI v9 or later (npm --version to verify).

Step 1: Configure the registry

Point npm at your CloudRepo registry:

npm config set registry=https://YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO/

Replace YOUR_ORG with your CloudRepo organization id and YOUR_REPO with the npm repository’s name. Include the trailing slash — without it, npm may fail to resolve packages correctly.

Step 2: Authenticate with `_auth`

CloudRepo usernames are email addresses, so the interactive npm login flow is not the path to use here — see Interactive npm login below for exactly what the registry does and does not accept. Configure credentials directly instead.

Generate the base64 value from your repository user’s email and password:

echo -n 'build-user@your-company.com:their-password' | base64

Then write it into .npmrc:

registry=https://YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO/
//YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO/:_auth=BASE64_ENCODED_CREDENTIALS
always-auth=true

Include always-auth=true — without it, npm only sends credentials for publish and not for install, which breaks private-package resolution.

The admin portal’s Connection Settings page for each repository shows this same configuration with your org and repository already filled in.

Step 3 (recommended for CI/CD): mint a bearer token

Once .npmrc authenticates, you can exchange those credentials for a bearer token. A token is revocable on its own — revoking it does not change the user’s password, and rotating the password does not require re-issuing every pipeline’s config.

npm token create --registry=https://YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO/

Reference the returned token as _authToken:

registry=https://YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO/
//YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO/:_authToken=YOUR_TOKEN
always-auth=true

Manage tokens against the same registry:

npm token list   --registry=https://YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO/
npm token revoke <token-id> --registry=https://YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO/

Step 4: Inject the credential at build time (don’t commit it)

Never commit an .npmrc containing a token or a base64 credential. Use your CI platform’s secret manager and write .npmrc at build time:

echo "//YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO/:_authToken=${CLOUDREPO_TOKEN}" >> .npmrc
echo "always-auth=true" >> .npmrc

Interactive `npm login`

The browser-based (“web”) login flow is not supported by CloudRepo. If your npm CLI attempts it, the registry responds:

{ "error": "Web login is not supported. Use npm login or configure authentication manually." }

The older --auth-type=legacy flow posts your credentials to a CouchDB-style user endpoint, which CloudRepo does accept — but modern npm CLI validates the username client-side and rejects email addresses (the @ character is not URL-safe per CouchDB user-document naming), printing npm warn Name may not contain non-url-safe chars. Since CloudRepo usernames are email addresses, configure .npmrc directly as shown above.

Troubleshooting

`npm install` returns 401

Cause: always-auth=true is missing from your .npmrc. Without it, npm only sends credentials for publish, not for install.

Fix: add always-auth=true to your .npmrc.

`npm warn Name may not contain non-url-safe chars`

Cause: you ran npm login --auth-type=legacy with an email-address username.

Fix: configure .npmrc directly (Step 2), or mint a bearer token (Step 3).

Trailing slash on registry URL

If npm install returns a 400 or 404, double-check that your registry URL ends with /:

# Correct
npm config set registry=https://YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO/

# Wrong (may cause issues)
npm config set registry=https://YOUR_ORG.mycloudrepo.io/repositories/YOUR_REPO

What’s next

Detailed npm guide — full reference covering scoped packages, multi-registry config, package-size limits, unpublishing, and token-based authentication.
JavaScript/Node.js overview — covers Yarn, pnpm, and Bun in addition to npm.
For help, the support widget on every CloudRepo page is the fastest path to a real human.