Publish npm packages to CloudRepo

View as Markdown

npm publishes to CloudRepo the way it publishes to any registry: the registry’s address and your token go in .npmrc, and npm publish uploads the package. This page is for the person who publishes a package. To install it, see npm repositories.

Before you start

An npm repository. If you have none, create one.
A repository token that reaches it, with Read + write. A Read only token can install but not publish: CloudRepo answers its npm publish with 403. See Repository tokens to create one. npm sends the token on its own, as _authToken. There is no username.
Your repository’s registry URL, https://<organization>.mycloudrepo.io/repositories/<repository>/, with the trailing slash. Your organization’s name is the first part of your CloudRepo host, and the repository’s name is the one the admin portal shows.
A package name in lowercase letters, digits, hyphens, dots and underscores, scoped (@scope/name) or not.

Publish with npm publish

1. Put the registry and the credential in ~/.npmrc. npm replaces ${CLOUDREPO_TOKEN} with the environment variable of that name, so the file holds no token and can be copied or committed. Export the variable in the shell that runs npm, or in your CI’s secret store.

registry=https://your-org.mycloudrepo.io/repositories/your-repo/
//your-org.mycloudrepo.io/repositories/your-repo/:_authToken=${CLOUDREPO_TOKEN}

Keep the trailing / on both lines, and keep the second line identical to the registry URL without https:. npm sends the token only to the registry that prefix names, so if the two differ, even by the slash, npm sends no token at all. This sets CloudRepo as your default registry. To keep npmjs.org as the default and publish only this package to CloudRepo, see Publish to CloudRepo and install from elsewhere.

2. Check the connection.

npm whoami

Expected: npm prints your email address.

3. Publish. Run this in the directory of your package:

npm publish

Expected: npm prints + <name>@<version>.

4. Check that it landed.

npm view docs-npm version

Expected: npm prints the version you published. The package is also listed in the repository in the admin portal.

Scoped packages

A scope routes a package name to a registry. Name your package with a scope, and give npm one line that sends that scope to CloudRepo, in ~/.npmrc beside the token line from step 1:

@myscope:registry=https://your-org.mycloudrepo.io/repositories/your-repo/
//your-org.mycloudrepo.io/repositories/your-repo/:_authToken=${CLOUDREPO_TOKEN}

Then publish as usual. npm sends @myscope/* packages to CloudRepo, and every other package to its default registry. A scoped package needs this line to install, too: if npm install @myscope/name answers 404, npm is asking the default registry, and the line is missing.

Publish to CloudRepo and install from elsewhere

If npmjs.org stays your default registry, name CloudRepo in the package itself. publishConfig in package.json makes npm publish go there, whatever your default registry is. The token line stays in ~/.npmrc:

{
  "name": "my-package",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://your-org.mycloudrepo.io/repositories/your-repo/"
  }
}

//your-org.mycloudrepo.io/repositories/your-repo/:_authToken=${CLOUDREPO_TOKEN}

Publish from CI

Keep the token in your CI’s secret store, expose it as the environment variable CLOUDREPO_TOKEN, and let .npmrc name the variable, as in step 1. Then the build runs plain npm:

npm publish

To write the .npmrc at build time, from the environment:

echo '//your-org.mycloudrepo.io/repositories/your-repo/:_authToken=${CLOUDREPO_TOKEN}' >> .npmrc

The single quotes matter: they write the text ${CLOUDREPO_TOKEN} into the file, and npm replaces it with the variable’s value when it runs, so the file never holds the token.

Never commit a token. Commit only the .npmrc that names the variable, and keep the variable itself in your CI platform’s secrets (GitHub Actions secrets, GitLab CI variables, Jenkins credentials).

Size

CloudRepo accepts an npm publish of up to 210 MiB (220,200,960 bytes), which holds a tarball of about 155 MiB: npm sends the tarball inside a JSON document, and base64 encoding adds about a third. A larger publish is refused with 413. If you need to publish larger packages, split them into several.

Publish a version once

Overwrite Protection is on by default for an npm repository. With it on, publishing a version that is already in the repository is refused with 409 Conflict, and the version already there stays as it is. npm prints CloudRepo’s explanation: Version already exists. Overwrites are disabled for this repository.

Increment the version in package.json and publish again. If the repository is meant to accept republished versions, turn Overwrite Protection off in its settings instead; see Overwrite Protection. npm has no mutable-version convention, so there is no equivalent of Maven’s -SNAPSHOT: no version is exempt.

When a publish is refused

Check these in order:

ENEEDAUTH, or “need auth”, and no request reached CloudRepo. npm sent no token. The //your-org.mycloudrepo.io/repositories/your-repo/: prefix on the _authToken line must match the registry= line exactly, without https: and with the trailing slash.
404 Not Found. npm sends _authToken as a Bearer token, and a Bearer that CloudRepo does not accept (mistyped, expired, or from another organization) answers 404, not 401. Check the variable is set (see above), that the token is whole, and that it has not expired: the Repository Tokens page in the admin portal shows its status.
403 Forbidden. The token cannot publish here. A Read only token cannot publish at all, and a token reaches only the repositories ticked when it was created. Use a Read + write token that includes this repository. A token that npm login wrote is also read-only unless you chose Read-write when you authorized it.
409 Conflict. The version is already in the repository. See above.
413. The publish is over 210 MiB (220,200,960 bytes). See above.

More: Repository tokens, for every client’s credential; and npm repositories, for installing, npm login, and taking a version back.