---
url: /en/artifact/npm.md
---
## 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

::: tabs

@tab npm
There are three ways:

#### 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.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.share.ralphlauren.cn/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.cnb.share.ralphlauren.cn/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.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# npm config set //npm.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/:_authToken=<YOUR_TOKEN>

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

@tab 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.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.share.ralphlauren.cn/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.cnb.share.ralphlauren.cn/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>" # Address for pushing packages
npmRegistryServer: "<REPO_URL>" # Address for pulling packages

npmRegistries:  # Configure credentials for each Artifact Registry
  "<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>
```

@tab 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.cnb.share.ralphlauren.cn/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.cnb.share.ralphlauren.cn/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:

::: tabs
@tab 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.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.share.ralphlauren.cn/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.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# npm config set //npm.cnb.share.ralphlauren.cn/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>}
```

@tab 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.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.share.ralphlauren.cn/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>}
```

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

### Pull Artifacts

::: tabs
@tab npm
For .npmrc configuration, refer to the following setup. Replace `<REPO_URL>` with the Artifact Registry address.

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: npm install
          script:
            - npm install --registry=<REPO_URL>
```

For npm config setup, refer to the following configuration. Replace `<REPO_URL>` with the Artifact Registry address and `<REPO_URL_SUFFIX>` with the Artifact Registry address without the protocol prefix.

```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>
```

@tab 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
```

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

### Push Artifacts

::: tabs
@tab npm
It is recommended to use the `tencentcom/npm` image. Paste the following content into .cnb.yml.

```yaml title=".cnb.yml"
$:
  # Triggered on tag push
  tag_push:
    - docker:
        image: node:22
      stages:
      - name: update version
        # $CNB_BRANCH is a built-in pipeline variable, representing the current tag
        # Update the version in package.json to the current tag without committing the code
        script: npm version $CNB_BRANCH --no-git-tag-version
      - name: npm publish
        image: tencentcom/npm
        settings:
          # $CNB_TOKEN_USER_NAME, $CNB_TOKEN, and $CNB_COMMITTER_EMAIL are built-in pipeline variables
          username: $CNB_TOKEN_USER_NAME
          token: $CNB_TOKEN
          email: $CNB_COMMITTER_EMAIL
          registry: <REPO_URL>
          folder: ./
          fail_on_version_conflict: true
```

@tab Yarn
If your Yarn version is 1.x:

```yaml title=".cnb.yml"
$:
  # Triggered on tag push
  tag_push:
    - docker:
        image: node:22
      stages:
      - name: install yarn
        script: 
          - npm install -g corepack
          - corepack prepare yarn@1.22.22 --activate
      - name: update version
        # $CNB_BRANCH is a built-in pipeline variable, representing the current tag
        script: yarn version --new-version=$CNB_BRANCH 
      - name: yarn publish
        script: yarn publish     
```

If your Yarn version is > 1.x:

```yaml title=".cnb.yml"
$:
  # Triggered on tag push
  tag_push:
    - docker:
        image: node:22
      stages:
      - name: install yarn
        script: 
          # Additional pull of the tagged branch information
          - git pull origin main 
          - npm install -g corepack
          - corepack prepare yarn@4.9.2 --activate
      - name: update version
        # $CNB_BRANCH is a built-in pipeline variable, representing the current tag
        script: yarn version $CNB_BRANCH 
      # If using command-line setup for credentials, include the following stage
      # - name: yarn auth
      #   script:
      #     - yarn config set npmPublishRegistry <REPO_URL>
      #     - yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' ${CNB_TOKEN}
      - name: yarn publish
        script: yarn npm publish
```

@tab pnpm
If using command-line setup for credentials, paste the following into .cnb.yml. Replace `<REPO_URL>` with the Artifact Registry address and `<REPO_URL_SUFFIX>` with the Artifact Registry address without the protocol prefix.

```yaml title=".cnb.yml"
$:
  # Triggered on tag push
  tag_push:
    - docker:
        image: node:22
      stages:
      - name: install pnpm
        script: 
          - npm install --global corepack@latest
          - corepack enable pnpm
      - name: update version
        # $CNB_BRANCH is a built-in pipeline variable, representing the current tag
        # Update the version in package.json to the current tag without committing the code
        script: pnpm version $CNB_BRANCH --no-git-tag-version
      - name: login registry
        script: 
          - pnpm config set registry <REPO_URL>
          - pnpm config set //<REPO_URL_SUFFIX>:_authToken=${CNB_TOKEN}
      - name: pnpm publish
        script: pnpm publish --no-git-checks
```

If using .npmrc for credentials, paste the following into .cnb.yml.

```yaml title=".cnb.yml"
$:
  # Triggered on tag push
  tag_push:
    - docker:
        image: node:22
      stages:
      - name: install pnpm
        script: 
          - npm install --global corepack@latest
          - corepack enable pnpm
      - name: update version
        # $CNB_BRANCH is a built-in pipeline variable, representing the current tag
        # Update the version in package.json to the current tag without committing the code
        script: pnpm version $CNB_BRANCH --no-git-tag-version 
      - name: pnpm publish
        script: pnpm publish --no-git-checks
```

:::

## 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, refer to the official npm documentation.