---
url: /en/artifact/npm.md
description: >
  Guide for configuring credentials and using the CNB npm artifact registry to
  publish and install Node.js packages, covering local development and CI
  pipeline workflows.
---
## Prerequisites

1. [Create Artifact Registry](./intro.md#creating-an-artifact-registry)
2. [Obtain Artifact Registry Address](./intro.md#obtaining-the-artifact-registry-address)
3. [Create Access Token](./intro.md#creating-an-access-token)

## Local Development

### Configure Credentials

#### npm

Three methods are supported:

##### Configure credentials in .npmrc

Paste the following content into the .npmrc file in the same directory as package.json.

Replace `<YOUR_TOKEN>` with your token, `<REPO_URL>` with the Artifact Registry address,
and `<REPO_URL_SUFFIX>` with the Artifact Registry address without the protocol prefix.

```ini
# Example
# registry=https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=<YOUR_TOKEN>

registry=<REPO_URL>
always-auth=true
//<REPO_URL_SUFFIX>:_authToken=<YOUR_TOKEN>
```

##### Command-line interaction

1. Set the artifact registry, replace `<REPO_URL>` with the Artifact Registry address.

```bash
# Example
# npm config set registry https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/

npm config set registry <REPO_URL>
```

2. Use the interactive login command. Your username is `cnb`, and the password is your access token.

```bash
npm login
```

##### Command-line setup

Replace `<YOUR_TOKEN>` with your token, `<REPO_URL>` with the Artifact Registry address,
and `<REPO_URL_SUFFIX>` with the Artifact Registry address without the protocol prefix.

```bash
# Example
# npm config set registry https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# npm config set //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=<YOUR_TOKEN>

npm config set registry <REPO_URL>
npm config set //<REPO_URL_SUFFIX>:_authToken=<YOUR_TOKEN>
```

#### Yarn

##### Yarn 1.x Configuration

If your Yarn version is 1.x, you can configure credentials as follows:

###### Configure credentials in .npmrc

Paste the following content into the .npmrc file in the same directory as package.json.

Replace `<YOUR_TOKEN>` with your token, `<REPO_URL>` with the Artifact Registry address,
and `<REPO_URL_SUFFIX>` with the Artifact Registry address without the protocol prefix.

```ini
# Example
# registry=https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=<YOUR_TOKEN>

registry=<REPO_URL>
always-auth=true
//<REPO_URL_SUFFIX>:_authToken=<YOUR_TOKEN>
```

###### Command-line interaction

This command is only suitable for local artifact pushing. Replace `<REPO_URL>` with the Artifact Registry address.

```bash
# Example
# yarn config set registry https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/

yarn config set registry  <REPO_URL>
yarn publish
# .....
question npm password: Enter your token here
```

##### Yarn > 1.x Configuration

If your Yarn version is > 1.x, there are two solutions,
but both ultimately modify the .yarnrc.yml file in the same directory as package.json.

###### Modify .yarnrc.yml

Configure credentials in .yarnrc.yml. Replace `<REPO_URL>` with the Artifact Registry
address and `<YOUR_TOKEN>` with your token.

```yaml
npmPublishRegistry: "<REPO_URL>"
npmRegistryServer: "<REPO_URL>"

npmRegistries:
  "<REPO_URL>":
    npmAlwaysAuth: true
    npmAuthToken: <YOUR_TOKEN>
```

###### Command-line setup

Replace `<REPO_URL>` with the Artifact Registry address and `<YOUR_TOKEN>` with your token.

```bash
yarn config set npmPublishRegistry <REPO_URL> # Address for pushing packages
yarn config set npmRegistryServer <REPO_URL> # Address for pulling packages
yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' <YOUR_TOKEN>
```

This will generate the following .yarnrc.yml:

```yaml
npmPublishRegistry: "<REPO_URL>"
npmRegistryServer: "<REPO_URL>"
npmRegistries:
  "<REPO_URL>":
    npmAuthToken: <YOUR_TOKEN>
```

#### pnpm

Refer to npm, just replace `npm` with `pnpm` in the commands.

### Pull Artifacts

Replace `<PACKAGE_NAME>`, `<VERSION>`, and `<REPO_URL>`.

```bash
# Example
# npm install express@5.1.0 --registry=https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/

# npm
npm install <PACKAGE_NAME>@<VERSION> --registry=<REPO_URL>

# yarn
yarn add <PACKAGE_NAME>@<VERSION>

# pnpm
pnpm install <PACKAGE_NAME>@<VERSION> --registry=<REPO_URL>
```

### Push Artifacts

1. Initialize package.json. Replace `<PACKAGE_NAME>` and `<VERSION>`.

```json
{
  "name": "<PACKAGE_NAME>",
  "version": "<VERSION>",
  "description": "",
  "main": "index.js",
  "author": "",
  "license": "MIT"
}
```

2. Execute the following command to publish the package. Replace `<REPO_URL>` with the Artifact Registry address.

```bash
# <REPO_URL> example
# https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/

# npm
npm publish --registry=<REPO_URL>

# yarn version > 1.x
yarn npm publish

# yarn version 1.x
yarn publish --registry=<REPO_URL>

# pnpm
pnpm publish --registry=<REPO_URL>
```

## Cloud Native Build

### Configure Credentials

Cloud Native Build supports three ways to use tokens.
Refer to \[Using Tokens in Cloud Native Build and Development]
(./intro.md#using-tokens-in-workspaces-and-cloud-native-build).
Below are the specific client usage methods.

#### npm

##### Configure credentials in .npmrc

Paste the following content into the .npmrc file in the same directory as package.json.

Replace `<REPO_URL>` with the Artifact Registry address and `<REPO_URL_SUFFIX>`
with the Artifact Registry address without the protocol prefix.

```ini
# Example
# registry=https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=${CNB_TOKEN}

registry=<REPO_URL>
always-auth=true

# Method 1: Use built-in environment variable CNB_TOKEN
//<REPO_URL_SUFFIX>:_authToken=${CNB_TOKEN}

# Method 2: Directly use, replace <YOUR_TOKEN> with your token
//<REPO_URL_SUFFIX>:_authToken=<YOUR_TOKEN>

# Method 3: Secret Registry, replace <ENV_NAME> with your secret registry variable
# //<REPO_URL_SUFFIX>:_authToken=${<ENV_NAME>}
```

##### npm config setup

Replace `<REPO_URL>` with the Artifact Registry address and `<REPO_URL_SUFFIX>`
with the Artifact Registry address without the protocol prefix.

```bash
# Example
# npm config set registry https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# npm config set //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=${CNB_TOKEN}

npm config set registry <REPO_URL>

# Method 1: Use built-in environment variable CNB_TOKEN
npm config set //<REPO_URL_SUFFIX>:_authToken=${CNB_TOKEN}

# Method 2: Directly use, replace <YOUR_TOKEN> with your token
# npm config set //<REPO_URL>:_authToken=<YOUR_TOKEN>

# Method 3: Secret Registry, replace <ENV_NAME> with your secret registry variable
# npm config set //<REPO_URL>:_authToken=${<ENV_NAME>}
```

#### Yarn

##### Yarn 1.x Configuration

If your Yarn version is 1.x, you can configure credentials as follows:

Paste the following content into the .npmrc file in the same directory as
package.json. Replace `<REPO_URL>` with the Artifact Registry address and `<REPO_URL_SUFFIX>`
with the Artifact Registry address without the protocol prefix.

```ini
# Example
# registry=https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=${CNB_TOKEN}

registry=<REPO_URL>
always-auth=true

# Method 1: Use built-in environment variable CNB_TOKEN
//<REPO_URL_SUFFIX>:_authToken=${CNB_TOKEN}

# Method 2: Directly use, replace <YOUR_TOKEN> with your token
//<REPO_URL_SUFFIX>:_authToken=<YOUR_TOKEN>

# Method 3: Secret Registry, replace <ENV_NAME> with your secret registry variable
# //<REPO_URL_SUFFIX>:_authToken=${<ENV_NAME>}
```

##### Yarn > 1.x Configuration

If your Yarn version is > 1.x, there are two solutions,
but both ultimately modify the .yarnrc.yml file in the same directory as package.json.

###### Modify .yarnrc.yml

```yaml
npmPublishRegistry: "<REPO_URL>" # Address for pushing packages
npmRegistryServer: "<REPO_URL>" # Address for pulling packages

npmRegistries:  # Configure credentials for each Artifact Registry
  "<REPO_URL>":
    npmAlwaysAuth: true
    # Method 1: Use built-in environment variable CNB_TOKEN
    npmAuthToken: ${CNB_TOKEN}
    # Method 2: Directly use, replace <YOUR_TOKEN> with your token
    # npmAuthToken: <YOUR_TOKEN>
    # Method 3: Secret Registry, replace <ENV_NAME> with your secret registry variable
    # npmAuthToken: ${<ENV_NAME>}
```

###### Command-line setup

```bash
yarn config set npmPublishRegistry <REPO_URL> # Address for pushing packages
yarn config set npmRegistryServer <REPO_URL> # Address for pulling packages

# Method 1: Use built-in environment variable CNB_TOKEN
yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' ${CNB_TOKEN}

# Method 2: Directly use, replace <YOUR_TOKEN> with your token
# yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' <YOUR_TOKEN>

# Method 3: Secret Registry, replace <ENV_NAME> with your secret registry variable
# yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' ${<ENV_NAME>}
```

#### pnpm

Refer to npm, just replace `npm` with `pnpm` in the commands.

### Pull Artifacts

#### npm

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: npm install
          script:
            - npm config set registry <REPO_URL>
            - npm config set //<REPO_URL_SUFFIX>:_authToken=${CNB_TOKEN}
            - npm install --registry=<REPO_URL>
```

> If credentials are already configured via `.npmrc`, you can use
> `npm install --registry=<REPO_URL>` directly instead of the three commands above.

#### Yarn

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: yarn install
          script:
            - npm install -g corepack
            - corepack enable
            - corepack prepare yarn@1.22.22 --activate

            # If Yarn version > 1.x and using command-line setup, include the following two lines
            # - yarn config set npmRegistryServer <REPO_URL>
            # - yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' ${CNB_TOKEN}

            - yarn install
```

#### pnpm

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: pnpm install
          script:
            - pnpm config set registry <REPO_URL>
            - pnpm config set //<REPO_URL_SUFFIX>/:_authToken=${CNB_TOKEN}
            - pnpm install
```

### Push Artifacts

The core pattern: update the version number in `tag_push` event and publish.
Below is an example using npm (recommended `tencentcom/npm` plugin):

```yaml title=".cnb.yml"
$:
  tag_push:
    - docker:
        image: node:22
      stages:
        - name: update version
          script: npm version $CNB_BRANCH --no-git-tag-version
        - name: npm publish
          image: tencentcom/npm
          settings:
            username: $CNB_TOKEN_USER_NAME
            token: $CNB_TOKEN
            email: $CNB_COMMITTER_EMAIL
            registry: <REPO_URL>
            folder: ./
            fail_on_version_conflict: true
```

For other package managers (replace the corresponding npm stages above):

* **Yarn 1.x**: Install `yarn@1.x`, update version with
  `yarn version --new-version=$CNB_BRANCH`, publish with `yarn publish`.
* **Yarn > 1.x**: Install `yarn@4.x`, update version with `yarn version $CNB_BRANCH`, publish with `yarn npm publish`.
* **pnpm**: Install `pnpm`, update version with
  `pnpm version $CNB_BRANCH --no-git-tag-version`, configure credentials
  with `pnpm config set`, then `pnpm publish --no-git-checks` to publish.

## Workspaces

### Configure Credentials

Same as [Cloud Native Build Configure Credentials](./npm.md#configure-credentials-1)

### Configure Development Image

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        image: node:22
```

You can execute the following command to select a package manager.
Replace `<NAME>` and `<VERSION>` with your package manager name and version.

```bash
npm install -g corepack
corepack enable
# Example: corepack prepare yarn@1.22.22 --activate
corepack prepare <NAME>@<VERSION> --activate
```

### Pull Artifacts

Same as [Local Development Pull Artifacts](./npm.md#pull-artifacts)

### Push Artifacts

Same as [Local Development Push Artifacts](./npm.md#push-artifacts)

## More Usage

For more npm usage, please refer to the [npm official documentation](https://docs.npmjs.com/).