CNB Docs

English

简体中文

English

简体中文
简体中文

Appearance

npm Artifact Registry

Copy page

About 1518 wordsAbout 5 min

npm Artifact Registry stores and distributes Node.js packages, read and written with npm, yarn, or pnpm.

When to use: when a team needs to publish private npm packages, or make a frontend project install dependencies from the CNB registry - configure credentials and publish/install as shown below.

Prerequisites

  1. Create Artifact Registry
  2. Obtain Artifact Registry Address
  3. Create 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.

# Example
# registry=https://npm.cnb.cool/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.cool/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.
# Example
# npm config set registry https://npm.cnb.cool/cnb/npm-repo/-/packages/

npm config set registry <REPO_URL>
  1. Use the interactive login command. Your username is cnb, and the password is your access token.
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.

# Example
# npm config set registry https://npm.cnb.cool/cnb/npm-repo/-/packages/
# npm config set //npm.cnb.cool/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.

# Example
# registry=https://npm.cnb.cool/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.cool/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.

# Example
# yarn config set registry https://npm.cnb.cool/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.

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.

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:

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

# Example
# npm install express@5.1.0 --registry=https://npm.cnb.cool/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>.
{
  "name": "<PACKAGE_NAME>",
  "version": "<VERSION>",
  "description": "",
  "main": "index.js",
  "author": "",
  "license": "MIT"
}
  1. Execute the following command to publish the package. Replace <REPO_URL> with the Artifact Registry address.
# <REPO_URL> example
# https://npm.cnb.cool/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.

# Example
# registry=https://npm.cnb.cool/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.cool/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.

# Example
# npm config set registry https://npm.cnb.cool/cnb/npm-repo/-/packages/
# npm config set //npm.cnb.cool/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.

# Example
# registry=https://npm.cnb.cool/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.cool/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
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
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

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

Tips

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

Yarn

.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

.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):

.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

Configure Development Image

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

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

Push Artifacts

Same as Local Development Push Artifacts

More Usage

For more npm usage, please refer to the npm official documentation.

© 2026 cnb.cool