> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/npm.md).

# npm

npm - publish packages to Harness Artifacts

Use an **npm** registry to host private npm packages for Node.js projects. The registry works with the npm CLI.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## Before you begin

* Install Node.js and the npm CLI (`npm`) on your local machine.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create an npm registry

To create an npm registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **npm** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch npm packages from external sources, such as the public npm registry, when they are not available locally.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **npm** as the **Registry type**.
7. Select the **Source**: **npmjs** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL**.
8. Select the **Authentication method**.
   * **Anonymous**: No credentials required. This works for the public npm registry.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Bearer token**: Specify the token as a new or existing secret. Do not include the `Bearer` prefix in the secret text.

{% hint style="warning" %}
**Harness Secret Manager required**

Store the username, password, or bearer token for an authenticated upstream in Harness Secret Manager. Harness Artifacts does not support external secret managers for upstream authentication, and needs this setup to decrypt and validate credentials.
{% endhint %}

9. Optionally, configure **Metadata configuration** to control how long the registry caches metadata and not-found responses from the upstream source.

{% hint style="info" %}
**Metadata configuration**

The **Metadata cache TTL (seconds)** field controls how long cached metadata, such as a package index, stays valid before the registry fetches it again. The **Negative cache TTL (seconds)** field controls how long the registry caches a not-found response, so it does not repeat an upstream lookup for a package it already failed to find. Both fields accept a value from 0 to 604800 seconds (7 days) and default to 600 seconds (10 minutes); a value of 0 is treated as unset.

Metadata TTL does not remove cached packages. To delete cached packages, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

For the full field reference, go to [Configure metadata cache TTL](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md#configure-metadata-cache-ttl).
{% endhint %}

10. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing npm Artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Click **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Click **Apply**.
7. Select **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If a package is not found in your Harness registry, the upstream proxy fetches it from the remote registry and caches it.
{% endhint %}

## npm client setup

In your npm Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for the npm CLI.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your npm Artifact, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. You use it in the following steps in place of `<IDENTITY_TOKEN>`.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

Replace the values in angle brackets with your own values.

**1. Configure**

Create or update `~/.npmrc` with the following content:

{% code title="\~/.npmrc" overflow="wrap" %}

```ini
registry=https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/npm/
//pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/npm/:_authToken=<IDENTITY_TOKEN>
```

{% endcode %}

**2. Publish a package**

Build and publish your package:

```bash
npm run build
npm publish
```

**3. Use a package**

Install the package:

```bash
npm install <PACKAGE_NAME>@<VERSION>
```

{% hint style="info" %}
**Usage**

These commands upload or retrieve npm packages between your local project and your Harness registry.
{% endhint %}

## Setup verification

Confirm that your registry serves the package you published. To verify your setup:

1. In a new project directory with no cached copy of the package you published, no matching entry in `node_modules`, and no matching entry in the global npm cache, install the package using the client command from the earlier steps.
2. Confirm that the client installed the package from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the package and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step shows the shape of a publish step. Replace `<ACCOUNT_ID>` and `<REGISTRY_NAME>` with the values from the earlier steps. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        npm version "$PACKAGE_VERSION" --no-git-tag-version
        npm publish
```

## Troubleshooting

<details>

<summary>`npm publish` fails with `401 Unauthorized` or `403 Forbidden`</summary>

Check that the `registry` and `_authToken` lines in `~/.npmrc` match the values shown in **Setup Client**. If the identity token expired or was revoked, generate a new one and update `~/.npmrc`.

</details>

<details>

<summary>`npm publish` returns `409 Conflict` or `EPUBLISHCONFLICT`</summary>

Package versions are immutable after publish. Bump the version in `package.json`, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`npm install` fails with `404 Not Found`</summary>

Check that the package name and version in your `npm install` command match the values you published, and that `~/.npmrc` points to the correct registry and account ID.

</details>

<details>

<summary>`npm install` resolves a stale version after a new publish</summary>

Clear the npm cache with `npm cache clean --force`, and remove the stale entry from `node_modules` or your lockfile before you reinstall.

</details>

<details>

<summary>**Setup Client** has no publish instructions on an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Setup Client** omits the publish instructions for it. Publish to a virtual npm registry instead, or cache packages from the upstream source through the upstream proxy.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
