# npm Repositories

> Use a CloudRepo npm repository: the registry URL, npm login and tokens in .npmrc, publishing, scoped packages, unpublishing and the 409 Conflict.

Use the npm CLI with a CloudRepo npm repository: publish your packages to it and install them from it.

Updated October 21: if you committed a project file that holds your CloudRepo password or token (`.npmrc`, `.yarnrc.yml` or `bunfig.toml`), change your password or revoke that token, and use `npm login` instead.

## Before you start

- Node.js and npm. Use npm 10.9.4 or later.
- A CloudRepo npm repository. If you have none, see [Creating a Repository](/docs/manage/repositories.html#creating-a-repository).
- A way to sign in: on your machine, an account that can sign in to the [admin portal](https://admin.cloudrepo.io), to run `npm login`; in CI, a repository token (see [Repository Tokens: Create One and Authenticate](/docs/authenticate/repository-tokens.html)). npm sends the token alone, as `_authToken` in `.npmrc`. There is no username.

## Connect npm

There are two ways to sign npm in. On your own machine, `npm login` signs you in through your browser and saves a token for you, so there is nothing to copy. In CI, a token kept in an environment variable signs npm in, with no browser.

### On your machine: npm login

Run `npm login` with your repository’s URL, ending in `/`:

**Terminal**

```bash
npm login --registry https://your-org.mycloudrepo.io/repositories/your-repo/
```

npm opens `https://admin.cloudrepo.io/npm-login?session=<id>` in your browser. Sign in to CloudRepo there, the way you sign in to the admin portal (or use the portal session you already have), and click **Authorize** on the **Authorize npm CLI** page. npm saves the token in `~/.npmrc` for you.

If your organization enforces SSO, sign in through your identity provider, as you do for the admin portal. With SSO, the token can also stop working before it expires, on its renewal date. Only a sign-in through your identity provider renews it. **Repository Tokens** shows that date as **Renew by**, under **Expires**.

The token `npm login` saves:

- reaches only the repository you ran it against;
- is read-only, unless you choose **Read-write** on the **Authorize npm CLI** page and your user has write access to the repository. `npm publish` needs **Read-write**;
- expires after 90 days;
- is listed on the **Repository Tokens** page as **npm-login web token**, where you can revoke it.

Run `npm login` against a Hosted npm repository. A Proxy npm repository refuses its token with `403` (`npm_token_not_supported_on_proxy`), even though `npm login` succeeds, and a group refuses `npm login` itself. For a Proxy repository or a group, use a token from **Repository Tokens**, as in CI below.

Then send your scope to the repository, in the `.npmrc` beside your `package.json`. It needs no token line: npm reads the token from `~/.npmrc`. Every other package still comes from the public npm registry. Replace `@yourscope` with your scope.

`.npmrc (npm login)`

```ini
@yourscope:registry=https://your-org.mycloudrepo.io/repositories/your-repo/
```

Check the connection, naming the repository:

**Terminal**

```bash
npm whoami --registry https://your-org.mycloudrepo.io/repositories/your-repo/
```

Publish from the directory of your package to the same URL:

**Terminal**

```bash
cd my-package
npm publish --registry https://your-org.mycloudrepo.io/repositories/your-repo/
```

If the terminal never returns after you authorize, the session expired: it lasts five minutes. Run `npm login` again.

### In CI: a token in an environment variable

Use a token from **Repository Tokens** (see [Repository Tokens: Create One and Authenticate](/docs/authenticate/repository-tokens.html)), or an [organization token](/docs/authenticate/repository-tokens.html#service-keys-for-your-pipelines), which belongs to your organization rather than to a person. Keep it in your CI’s secret store and expose it as the environment variable `NPM_TOKEN`. Never put the token itself in a file you commit.

**npm**

**1. Put your scope and the credential in `~/.npmrc`.** npm replaces `${NPM_TOKEN}` with the environment variable of that name, so the file holds no token and can be copied or committed:

`~/.npmrc`

```ini
@yourscope:registry=https://your-org.mycloudrepo.io/repositories/your-repo/
//your-org.mycloudrepo.io/repositories/your-repo/:_authToken=${NPM_TOKEN}
```

Send your scope’s packages to this repository; every other package still comes from the public npm registry. Replace `@yourscope` with your scope.

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: if the two differ, even by the slash, npm sends no token at all. npm sends the token on every request to that registry, installs included, so no `always-auth` setting is needed (npm 11 warns that `always-auth` is an unknown option).

**2. Check the connection.**

**Terminal**

```bash
npm whoami --registry https://your-org.mycloudrepo.io/repositories/your-repo/
npm ping --registry https://your-org.mycloudrepo.io/repositories/your-repo/
```

Expected: `npm whoami` prints your email address, and `npm ping` ends with `PONG`.

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

**Terminal**

```bash
npm publish --registry https://your-org.mycloudrepo.io/repositories/your-repo/
```

A package may be scoped (`@scope/name`) or unscoped. The publish names the repository, so a package without your scope won’t go to the public registry.

**4. Install it from another project.** A package of your scope installs in any project through the line in step 1. The example package, `docs-npm`, has no scope, so the new project below names the repository. Run that install in a new, empty project, as below: in a project with other dependencies, `--registry` sends npm to this repository for them too, and it holds only what was published to it.

**Terminal**

```bash
mkdir consumer && cd consumer
npm init -y
npm install docs-npm --registry https://your-org.mycloudrepo.io/repositories/your-repo/
```

**Basic authentication.** Some older CI tooling needs `_auth`. Its value is the base64 of your email address, a colon and the token. Build it from the variable:

**Terminal**

```bash
printf '%s' "you@example.com:$NPM_TOKEN" | base64
```

`~/.npmrc`

```ini
@yourscope:registry=https://your-org.mycloudrepo.io/repositories/your-repo/
//your-org.mycloudrepo.io/repositories/your-repo/:_auth=BASE64_ENCODED_CREDENTIALS
```

Prefer `_authToken` above: it needs no encoding step.

The legacy `npm login --auth-type=legacy` flag is no longer supported. CloudRepo answers it with `410 Gone` and points you at the web login or a repository token. Modern npm rejects an email address as a username, and CloudRepo’s users are identified by email address.

## Use Yarn

Yarn 2 and later read the registry from `npmRegistryServer` in the project’s `.yarnrc.yml`. Set it in your scope’s `npmScopes` entry, never at the top of the file: there it sends every package to this repository, which holds only what was published to it, so every public package answers `404`. Replace `yourscope` with your scope, without the `@`. Set the environment variable `NPM_TOKEN` to a repository token (see [Repository Tokens: Create One and Authenticate](/docs/authenticate/repository-tokens.html)). The file names the variable and holds no token.

`.yarnrc.yml`

```yaml
npmScopes:
  yourscope:
    npmRegistryServer: "https://your-org.mycloudrepo.io/repositories/your-repo/"
    npmPublishRegistry: "https://your-org.mycloudrepo.io/repositories/your-repo/"
    npmAuthToken: "${NPM_TOKEN}"
```

Yarn 4.15 and later wait a day before installing a newly published version. On Yarn 4.17 and later, add this to your scope’s block to install your own packages the day you publish them. On 4.15 or 4.16, update Yarn or install the next day.

`.yarnrc.yml (scoped, same-day installs)`

```yaml
npmScopes:
  yourscope:
    npmRegistryServer: "https://your-org.mycloudrepo.io/repositories/your-repo/"
    npmPublishRegistry: "https://your-org.mycloudrepo.io/repositories/your-repo/"
    npmAuthToken: "${NPM_TOKEN}"
    npmMinimalAgeGate: 0
```

This lets Yarn install versions you published today from your own repository. Delete that line to keep Yarn’s one-day delay.

## Scoped packages and several registries

To install private packages from CloudRepo and everything else from the default registry, route a scope to CloudRepo in `.npmrc`:

`.npmrc`

```ini
@yourscope:registry=https://your-org.mycloudrepo.io/repositories/your-repo/
//your-org.mycloudrepo.io/repositories/your-repo/:_authToken=${NPM_TOKEN}
```

This sends `@yourscope/*` packages to CloudRepo and every other package to npm’s default registry. CloudRepo accepts both scoped (`@scope/name`) and unscoped packages.

To publish a scoped package, create it with the scope and publish as usual:

**Terminal**

```bash
npm init --scope=@yourscope -y
npm publish
```

If `npm install @scope/package` answers `404`, npm is asking the default registry for that scope. Add the scope line above.

## Package size limit

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

### Very large packages through a proxy

A few public packages, like `@prisma/client`, carry more metadata than a proxy repository reads (over 64 MiB, or over 3,145,728 JSON values). For those, your npm proxy hands npm the smaller install metadata together with every version’s publish time, so `npm install`, `yarn add` and `npm install --before=<date>` work, and yarn’s default age gate reads the real publish dates. Two things differ for such a package:

- `npm view` shows fewer fields than npmjs does: the install metadata has no readme.
- A package whose install metadata is over the limit too, or whose publish times are over theirs (65,536 entries or 4 MiB), is refused with `502` (`upstream_packument_too_large`).

## Unpublish a package

Remove one version, or every version of a package. CloudRepo lets a write-capable credential unpublish any version at any time, and Overwrite Protection does not block it.

**Terminal**

```bash
npm unpublish my-package@1.0.0
npm unpublish my-package --force
```

> **Removing every version cannot be undone:** Prefer removing one version. Removing all versions is irreversible, and it may break builds that depend on any version of the package.

### Remove a package through the REST API

For scripts, the registry’s own paths remove a package too. Send the same credential as npm: put it in `~/.netrc` and ask curl to read it (see [Maven Repositories](/docs/formats/maven.html) for the file). First read the current revision from the package metadata, then delete with it.

To remove one version, delete its tarball with that revision:

**Terminal**

```bash
REVISION=$(curl --netrc --silent \
  https://your-org.mycloudrepo.io/repositories/your-repo/my-package/ \
  | jq -r '._rev')
curl --netrc --request DELETE \
  "https://your-org.mycloudrepo.io/repositories/your-repo/my-package/-/my-package-1.0.0.tgz/-rev/$REVISION"
```

To remove the whole package, with all its versions:

**Terminal**

```bash
REVISION=$(curl --netrc --silent \
  https://your-org.mycloudrepo.io/repositories/your-repo/my-package/ \
  | jq -r '._rev')
curl --netrc --request DELETE \
  "https://your-org.mycloudrepo.io/repositories/your-repo/my-package/-rev/$REVISION"
```

## Token management

npm reads two kinds of CloudRepo token. The one the `npm login` web flow writes into your `.npmrc` has the npm format (`crn_v1_`) and works on hosted npm repositories only. One you create under **Repository Tokens** (`crp_v1_`, or `crk_v1_` for an organization token) works on every repository type it reaches. Each is revocable from the admin portal without affecting your login or your other credentials. See [Repository Tokens: Create One and Authenticate](/docs/authenticate/repository-tokens.html).

`npm token create` is not supported against CloudRepo: it answers `410 Gone` and points you at the portal.

`npm token list` and `npm token revoke <id>` act only on your `crn_v1_` (npm-format) tokens, and need write access to the repository named in `--registry`: with read-only access, they answer `403`.

npm sends the token `npm login` saved in `~/.npmrc` (see [On your machine: npm login](#on-your-machine-npm-login)) as a `Bearer` header on every later request to the registry.

### Run npm in CI

Keep the token in your CI platform’s secret store, expose it as the environment variable `NPM_TOKEN`, and let `.npmrc` name the variable, as in the first step. Then the build runs npm, and the publish names the repository:

**Terminal**

```bash
npm install
npm publish --registry https://your-org.mycloudrepo.io/repositories/your-repo/
```

To write the `.npmrc` at build time instead:

**Terminal**

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

The single quotes matter: they write the text `${NPM_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:** Use your CI platform’s secret management (GitHub Actions secrets, GitLab CI variables, Jenkins credentials) to supply the token at build time, and commit only the `.npmrc` that names the variable.

npm logout revokes the token it presents, even if CI also uses it.

## Troubleshooting

### 401, 403 or 404 on `npm install`

npm sends `_authToken` as a Bearer token. A token that is mistyped, expired, revoked or from another organization answers `404 Not Found`, not `401`, so npm reports the package as not found. If npm reports `404` for a package you know exists, check the token first. Check, in order:

- The `//your-org.mycloudrepo.io/repositories/your-repo/:` prefix on the `_authToken` line matches the URL on your `@yourscope:registry=` line, and the one you pass to `--registry`, exactly, without `https:` and with the trailing slash.
- If the package is a public one, such as `react`: your `.npmrc` has a `registry=` line that sends every package to a hosted repository, which holds only what was published to it. Replace it with the `@yourscope:registry=` line of step 1.
- The token reaches this repository. A token from `npm login` (`crn_v1_`) works only on the hosted npm repository you logged in to, and a proxy npm repository refuses it with `403`: use a token from **Repository Tokens** for a proxy repository.
- If `npm publish` answers `403`: a token from `npm login` is read-only unless you chose **Read-write** when you authorized it and your user has write access.
- The token has not expired or been revoked: check the **Repository Tokens** page.

### The registry URL has no trailing slash

When the registry URL or the token prefix lacks the trailing slash, they no longer match, so npm sends no token and commands fail as if you had not signed in. End both with `/`. This is right:

**Terminal**

```bash
npm config set @yourscope:registry https://your-org.mycloudrepo.io/repositories/your-repo/
```

The same command without the last `/` (`.../repositories/your-repo`) is wrong: the prefix on the token line no longer matches.

### `npm publish` fails with “Version already exists”

`npm publish` answers `409 Conflict` when a package with that version already exists and [Overwrite Protection](/docs/manage/repositories.html#overwrite-protection) is on, which is the default on every npm repository. npm prints CloudRepo’s explanation: `Version already exists. Overwrites are disabled for this repository.`

Increment the version in `package.json` before publishing. If the repository is meant to accept republished versions, turn Overwrite Protection off in its settings instead. npm has no mutable-version convention, so there is no equivalent of Maven’s `-SNAPSHOT` escape hatch here: no version is exempt.

## Next steps

- [Repository Management](/docs/manage/repositories.html): repository configuration options.
- [Continuous Integration and Deployment](/docs/ci/overview.html): CI/CD pipeline integration.

---

The page: https://www.cloudrepo.io/docs/formats/npm.html
