<!– 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 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.